MCP服务器集合

MCP Servers

This repository contains six MCP servers implemented in Python 3.12+ with uv, FastMCP, ruff, mypy, and pytest.

Every command uses stdio by default for direct MCP client integration. Pass --transport http (or set MCP_TRANSPORT=http) to expose:

• POST /mcp for the MCP transport
• GET /healthz for a basic health check

Repository: cofob/mcps

Services

email-mcp

IMAP/SMTP email MCP server for multiple named accounts.

Highlights:

• list folders and list, search, read, or fetch RFC-header-linked message threads without changing read state
• fetch complete attachments as MCP binary resources
• send plain-text/HTML messages from a configured default or per-message From address with bounded base64 attachments
• reply or reply-all with recipients derived from the source message and standards-compliant In-Reply-To and References headers
• sign outgoing MIME bodies and attachments with OpenPGP/MIME through a configured GPG keyring and agent
• expose mandatory confirmation and direct-request privacy rules plus a detailed skill://email-mcp/usage resource

Package: services/email_mcp

Published image:

• ghcr.io/cofob/email-mcp

filesystem-mcp

Filesystem MCP server for one configured root directory.

Highlights:

• read files and metadata
• list directories and trees
• search by filename and file contents
• write, copy, move, delete, modify, and patch files

Package: services/filesystem_mcp

Published image:

• ghcr.io/cofob/filesystem-mcp

navidrome-mcp

Remote MCP server for Navidrome using its Subsonic-compatible API.

Highlights:

• search artists, albums, tracks, and playlists
• fetch artist, album, track, and playlist details
• list artists, albums, playlists, starred items, and random tracks
• rate, like, unlike, and manage playlists

Package: services/navidrome_mcp

Published image:

• ghcr.io/cofob/navidrome-mcp

mikrotik-mcp

Secure RouterOS 7 CLI MCP server for multiple named MikroTik device profiles.

Highlights:

• reuse one serialized interactive SSH connection per profile
• pin the exact confirmed SSH host key and keep credentials out of agent configuration
• enter RouterOS Safe Mode by default and expose explicit save and rollback tools
• require the client's destructive-tool approval for unsafe commands and saving changes
• reject unsafe execution while floating Safe Mode changes remain unresolved

Package: services/mikrotik_mcp

Published image:

• ghcr.io/cofob/mikrotik-mcp

slskd-mcp

Remote MCP server for slskd.

Highlights:

• create and inspect searches
• inspect users and browse shares
• request downloads
• inspect and manage downloads and uploads
• list files from configured slskd locations

Package: services/slskd_mcp

Published image:

• ghcr.io/cofob/slskd-mcp

tg-export-txt-mcp

Read-only MCP server for TXT exports generated by tg_backup.

Highlights:

• run_cli runs a raw Bash command line inside the export root and is the preferred tool for direct full-text rg search workflows
• list_export_files recursively lists .txt files below a root-relative export path
• list_chats reads chat_id<TAB>chat_name mappings from the top-level chats.txt
• search_chats does fuzzy search over exported chat ids and names
• list_topics reads topic_id<TAB>topic_name mappings from chats/<chat_id>/topics.txt
• search_topics does fuzzy search over exported topic ids and names for one forum chat
• read_export_file returns a line-range slice from one .txt export file
• search_exports uses rg --json with ranking, metadata, and optional chat/topic/date/path filters
• access is restricted to one configured export root

Package: services/tg_export_txt_mcp

Published image:

• ghcr.io/cofob/tg-export-txt-mcp

Workspace Layout

packages/
  mcp_common/
services/
  email_mcp/
  filesystem_mcp/
  mikrotik_mcp/
  navidrome_mcp/
  slskd_mcp/
  tg_export_txt_mcp/
docker/
tests/

• packages/mcp_common contains shared settings, HTTP, auth, and tool-registration helpers.
• Each service is a separate workspace package under services.
• Shared tests live under tests.

Development

Requirements:

• Python 3.12+
• uv

Install the workspace:

uv sync --all-packages --group dev

Quality checks:

uv run ruff check .
uv run mypy packages services tests src
uv run pytest

Interactive Installation

Install one or more services into supported local coding agents without publishing anything to PyPI:

uvx --no-cache --refresh --from 'git+https://github.com/cofob/mcps.git' install

--no-cache --refresh makes uv use a temporary cache and refresh the Git source instead of reusing a previous checkout.

The wizard:

• detects Codex, Claude Code, OpenCode, and Gemini CLI and lets you select multiple installed agents
• configures named profiles for Email, Filesystem, MikroTik, Navidrome, slskd, and Telegram TXT export
• validates remote credentials and local paths before writing configuration
• stores passwords and API keys in the system keyring, with an explicit restricted-file fallback
• reconfigures existing profiles with saved non-secret defaults and an option to retain each stored password or API key without displaying it
• performs an MCP stdio initialization and tool-discovery smoke test
• previews every profile and asks before replacing existing profile or agent entries

Installed agent entries contain no credentials. They invoke a named profile through the Git checkout's generic runner:

uvx --from git+https://github.com/cofob/mcps.git mcps-run email --profile personal

Profiles use the platform user-configuration directory returned by platformdirs. Non-secret settings live in config.json. Keyring credentials use the cofob.mcps service name. When restricted-file storage is explicitly selected, secrets live in secrets.json; the installer creates the directory with user-only permissions and uses mode 0600 on POSIX systems.

Re-run install and select Reconfigure an existing profile to update one in place. The wizard preserves its current secret-store backend, lets you keep saved credentials without re-entering them, validates and smoke-tests the revised profile, and previews the replacement before writing. Existing agent configuration is backed up with an .mcps-backup-<timestamp> suffix before replacement. Use these options for troubleshooting or automation:

# Deliberately use the restricted local secrets file
uvx --no-cache --refresh --from 'git+https://github.com/cofob/mcps.git' install --secret-store file

# Configure without network or credential checks; the profile is marked unverified
uvx --no-cache --refresh --from 'git+https://github.com/cofob/mcps.git' install --skip-validation

For a new MikroTik device, --skip-validation skips authentication and RouterOS version checks but still retrieves and requires confirmation of the SSH host key; secure host-key pinning cannot be skipped.

Email setup includes Gmail, Outlook.com, iCloud Mail, and Fastmail presets plus custom verified-TLS IMAP/SMTP settings and a default From address. email_send_message can override that address for one message. Validation logs in to IMAP, selects INBOX read-only, authenticates to SMTP, and runs NOOP; it never sends a test message. Gmail, iCloud, and Fastmail commonly require app-specific passwords. Outlook.com normally requires OAuth2/Modern Auth, which is not supported by the password/app-password email service and may fail validation.

MikroTik setup supports multiple device profiles in one registered MCP instance. The wizard fetches each SSH host key, shows its SHA-256 fingerprint for operator verification, and pins the exact confirmed key. Credential validation enters Safe Mode, reads the RouterOS version, requires RouterOS 7, and exits with rollback.

Direct Git Usage With uv

The installable workspace root exposes one launcher per service without publishing any package to PyPI. Pin a tag or commit in production MCP client configuration:

uvx --from 'git+https://github.com/cofob/mcps.git@<tag-or-commit>' mcps-email
uvx --from 'git+https://github.com/cofob/mcps.git@<tag-or-commit>' mcps-filesystem
uvx --from 'git+https://github.com/cofob/mcps.git@<tag-or-commit>' mcps-mikrotik
uvx --from 'git+https://github.com/cofob/mcps.git@<tag-or-commit>' mcps-navidrome
uvx --from 'git+https://github.com/cofob/mcps.git@<tag-or-commit>' mcps-slskd
uvx --from 'git+https://github.com/cofob/mcps.git@<tag-or-commit>' mcps-tg-export-txt

Example MCP client entry using stdio:

{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/cofob/mcps.git@<tag-or-commit>", "mcps-email"],
  "env": {
    "EMAIL_ACCOUNTS": "{\"personal\":{\"imap_host\":\"imap.example.com\",\"smtp_host\":\"smtp.example.com\",\"username\":\"alice@example.com\",\"password\":\"app-password\",\"default_from_address\":\"alice@example.com\"}}"
  }
}

Running Locally

Run services from the workspace root. The examples below select HTTP explicitly; omit --transport http for stdio.

Email

export EMAIL_ACCOUNTS='{"personal":{"imap_host":"imap.example.com","smtp_host":"smtp.example.com","username":"alice@example.com","password":"app-password","default_from_address":"alice@example.com","from_name":"Alice"}}'
export HOST="0.0.0.0"
export PORT="8084"

uv run --package email-mcp email-mcp --transport http

See the email service README for attachments, limits, and GPG setup. Email agents must preview complete message bodies and receive explicit confirmation before each send. Account, folder, and message listing and message search are allowed only when directly requested by the user. After SMTP submission, email-mcp saves a copy through IMAP in the discovered Sent mailbox; set the optional per-account sent_folder field when the server does not advertise a standard Sent folder.

Navidrome

export NAVIDROME_URL="https://navidrome.example.com"
export NAVIDROME_USERNAME="alice"
export NAVIDROME_PASSWORD="secret"
export HOST="0.0.0.0"
export PORT="8080"

uv run --package navidrome-mcp navidrome-mcp --transport http

MikroTik

export MIKROTIK_PROFILES='{"core":{"transport":"ssh","host":"10.0.0.1","port":22,"username":"agent","password":"secret","host_key":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA..."}}'
export HOST="0.0.0.0"
export PORT="8086"

uv run --package mikrotik-mcp mikrotik-mcp --transport http

See the MikroTik service README for the Safe Mode lifecycle, host-key pinning, approval boundary, supported tools, and RouterOS account guidance.

slskd

API key mode:

export SLSKD_URL="https://slskd.example.com"
export SLSKD_API_KEY="your-api-key"
export HOST="0.0.0.0"
export PORT="8081"

uv run --package slskd-mcp slskd-mcp --transport http

Username/password mode:

export SLSKD_URL="https://slskd.example.com"
export SLSKD_USERNAME="alice"
export SLSKD_PASSWORD="secret"
export HOST="0.0.0.0"
export PORT="8081"

uv run --package slskd-mcp slskd-mcp --transport http

Filesystem

export FILESYSTEM_ROOT_DIR="/srv/data"
export HOST="0.0.0.0"
export PORT="8082"

uv run --package filesystem-mcp filesystem-mcp --transport http

tg-export-txt

export TG_EXPORT_TXT_ROOT_DIR="/path/to/tg_backup/txt"
export TG_EXPORT_TXT_RG_PATH="rg"
export TG_EXPORT_TXT_MAX_READ_LINES="400"
export TG_EXPORT_TXT_MAX_SEARCH_RESULTS="200"
export HOST="0.0.0.0"
export PORT="8083"

uv run --package tg-export-txt-mcp tg-export-txt-mcp --transport http

Common Configuration

All services share these environment variables through mcp_common:

• HOST
• PORT
• LOG_LEVEL
• TIMEOUT_SECONDS
• MCP_TRANSPORT
• MCP_AUTH_MODE

Defaults:

• HOST=0.0.0.0
• PORT=8080
• LOG_LEVEL=INFO
• TIMEOUT_SECONDS=20.0
• MCP_TRANSPORT=stdio
• MCP_AUTH_MODE=none

Tool gating is also shared across services via the nested TOOLS settings object.

Example:

export TOOLS='{"disabled_tool_groups":["mutate"]}'

Docker And CI

Dockerfiles live under docker.

Current CI in ci.yml:

• runs ruff, mypy, and pytest on pull requests to main
• runs the same lint/test job on tag pushes matching v*
• builds Docker images after the lint job
• pushes images to GHCR only on non-PR runs, which in the current workflow means tag pushes

Docker images currently built by CI:

• ghcr.io/cofob/email-mcp
• ghcr.io/cofob/filesystem-mcp
• ghcr.io/cofob/mikrotik-mcp
• ghcr.io/cofob/navidrome-mcp
• ghcr.io/cofob/slskd-mcp
• ghcr.io/cofob/tg-export-txt-mcp

HTTP Endpoints

When started with --transport http, every service exposes:

• GET /healthz
• POST /mcp

Example health response:

{
  "status": "ok",
  "service": "navidrome-mcp",
  "version": "0.1.0"
}