BaseMcpServer

View on GitHub

A minimal containerized base for MCP servers using the MCP Python SDK

3 stars PythonOthers Updated Aug 24, 2026

Documentation

BaseMcpServer

A monorepo of Model Context Protocol servers plus the `mcp-manager` CLI that installs and configures them.

What's in this repo

code

BaseMcpServer/
├── utils/mcp_manager/         # CLI for installing + managing MCP servers (canonical install path)
├── servers/
│   ├── jira-helper/           # Jira + Confluence integration server (multi-instance)
│   ├── worldcontext/          # Current-context tools (date/time, market, news, dev-tool versions)
│   ├── mcpservercreator/      # Generator that scaffolds new MCP servers from a code snippet
│   ├── loadbearing-youtube/   # Extract a YouTube transcript + expose its load-bearing components
│   └── template/              # Starter scaffold to fork when building a new server
├── docs/
│   ├── adr/                   # Architecture Decision Records
│   ├── developer/             # Implementation guides (build a new MCP server, client support, etc.)
│   └── user/                  # End-user docs (Cline compatibility, etc.)
└── QUICKSTART.md              # End-to-end jira-helper onboarding

Every server in this repo is a Python package installable via `mcp-manager install`, gets its own isolated `uv`-managed environment under `~/.config/mcp-manager/servers//.venv`, and can be wired into supported MCP clients with a single `mcp-manager sync` call. The repository currently supports and tests macOS and Linux; Windows is explicitly out of scope.

Quick install

bash

# 1. One-time: install uv and mcp-manager
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install "git+https://github.com/dawsonlp/BaseMcpServer.git#subdirectory=utils/mcp_manager"
uv tool update-shell

# 2. Install whichever servers you want
mcp-manager install jira-helper        --source ./servers/jira-helper
mcp-manager install worldcontext       --source ./servers/worldcontext
mcp-manager install mcpservercreator   --source ./servers/mcpservercreator
mcp-manager install loadbearing-youtube --source ./servers/loadbearing-youtube

# 3. Edit the per-server config files (where credentials go) — see each server's README
$EDITOR ~/.config/mcp-manager/servers/jira-helper/config.yaml

# 4. Wire the servers into installed supported clients
mcp-manager sync

For an end-to-end walkthrough with jira-helper (including Atlassian API token setup), see QUICKSTART.md.

Building a new MCP server

Fork `servers/template/` and follow the README inside it. Every server uses MCP Python SDK v2 directly: a `create_server()` factory constructs `MCPServer`, then registers plain tool functions through `add_tool()`. Decorator-based registration and MCP Commons are not used.

Detailed reference: `docs/developer/BUILD_A_NEW_MCP.md`.

For dynamically generating a server from a code snippet, see the `mcpservercreator` server itself, once installed.

Connecting clients

bash

mcp-manager sync      # sync every detected supported client
# or selectively:
mcp-manager sync --platform cline
mcp-manager sync --platform codex

`mcp-manager` supports Cline, Claude Desktop, Claude Code, VS Code native MCP, Codex, and Antigravity. It writes or delegates stdio entries that point at the executable in each server's managed environment. Restart the affected client for new entries to take effect.

Example entry (written automatically; shown for reference):

json

{
  "mcpServers": {
    "jira-helper": {
      "command": "/Users//.config/mcp-manager/servers/jira-helper/.venv/bin/jira-helper",
      "args": ["stdio"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Hand-added entries in your editor's settings file are preserved across `sync` — only entries that match a server name in the mcp-manager registry are overwritten.

Architecture decisions

The major directional choices are tracked under `docs/adr/`:

ADR-003 — current: all server installs go through `uv`
ADR-002 — superseded; documents the earlier pipx-default attempt

License

MIT License

Frequently asked questions

What is BaseMcpServer?

BaseMcpServer is A minimal containerized base for MCP servers using the MCP Python SDK

How do I install BaseMcpServer?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is BaseMcpServer open source?

Yes — it is hosted on GitHub at https://github.com/dawsonlp/BaseMcpServer and has 3 stars.

Related MCP tools

cognee

Cognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.

30,433 Python

agent-memoryagent-skillsai+16

skyvern

Automate browser based workflows with AI

22,930 Python

apiautomationbrowser+13

hindsight

Hindsight: Agent Memory That Learns

22,468 Python

agentic-aimemoryagents+1

watermarks-remover

A privacy-first app that strips AI watermarks from content you own.

20,504 Python

agent-skillaic2pa+12

Qwen-Agent

Agent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.

17,062 Python

pal-mcp-server

The power of Claude Code / GeminiCLI / CodexCLI + [Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / Custom Model / All Of The Above] working as one.

11,731 Python

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP