pingcode-mcp 0.1.0

MCP server for PingCode project management — manage projects, sprints, and work items via any MCP client.

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

Tool	Description
pingcode_list_projects	List accessible projects
pingcode_list_sprints	List sprints in a project
pingcode_list_work_items	Search/filter work items
pingcode_get_work_item	Get work item details
pingcode_create_work_item	Create a work item
pingcode_update_work_item	Update work item fields
pingcode_delete_work_item	Delete a work item
pingcode_get_work_item_types	Get types (story, bug, task...)
pingcode_get_work_item_states	Get states for a type
pingcode_get_work_item_priorities	Get priority levels

Configuration

Environment Variable	Required	Default	Description
PINGCODE_CLIENT_ID	Yes	—	OAuth2 client ID
PINGCODE_CLIENT_SECRET	Yes	—	OAuth2 client secret
PINGCODE_BASE_URL	No	https://open.pingcode.com	API base URL
PINGCODE_DEFAULT_PROJECT_ID	No	—	Default project ID

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