PingCode MCP Server

MCP server for PingCode project management. Manage projects, sprints, and work items (stories, bugs, tasks, epics) from any MCP client.

Built with Python, OAuth2 authentication, and the FastMCP framework.

Features

• 10 MCP tools covering full CRUD for work items, sprint listing, project listing, and metadata queries
• OAuth2 client credentials authentication (no browser required)
• Auto-pagination for large result sets
• Retry with exponential backoff on transient failures
• Docker support for one-command deployment

Quick Start

1. Get PingCode OAuth2 Credentials

In PingCode admin panel: Settings → Applications → Create App to obtain client_id and client_secret.

2. Configure

cp .env.example .env
# Edit .env with your credentials

3. Run

Option A: Docker (recommended)

docker compose up --build -d

Option B: Local (development)

pip install -e ".[dev]"
pingcode-mcp-server

4. Connect to Claude Code

Add to ~/.claude.json:

Docker mode:

{
  "mcpServers": {
    "pingcode-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/path/to/pingcode-mcp/.env", "pingcode-mcp:latest"]
    }
  }
}

Local mode (with uv):

{
  "mcpServers": {
    "pingcode-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pingcode-mcp", "pingcode-mcp-server"]
    }
  }
}

Tools

Configuration

Testing

# Install dev dependencies
pip install -e ".[dev]"

# Run unit tests
pytest tests/unit/

# Run unit tests with coverage
pytest tests/unit/ --cov=pingcode_mcp --cov-report=term-missing

# Run E2E tests (requires .env with real credentials)
pytest -m e2e

Project Structure

src/pingcode_mcp/
├── config.py      # Environment variable loading
├── client.py      # Async PingCode API client (OAuth2, retry, pagination)
├── server.py      # FastMCP entry point
└── tools/
    ├── projects.py    # Project listing
    ├── sprints.py     # Sprint listing
    ├── work_items.py  # Work item CRUD
    └── metadata.py    # Types, states, priorities

License

MIT