Skip to content

fxckcode/mcp-cor

BranchesTags

Repository files navigation

⬡ COR MCP Server

61 MCP tools for Project COR — the project management platform for creative and professional teams.

CI Python License Ruff uv MCP Docker Tests

Exposes the complete COR REST API surface as MCP tools — usable from any MCP-compatible client: Hermes Agent, Claude Desktop, Cursor, Claude Code, Cline, Windsurf, and more.

✨ Features

  • 61 MCP tools — full CRUD for all COR entities across 11 modules
  • Dual authentication — pick what suits you:
    • User Credentials (email + password) — quick personal use
    • Client Credentials (API key + client secret) — server-to-server
  • Async everywhere — httpx + asyncio, non-blocking I/O
  • Dual transport — stdio (default for agents) and sse (HTTP for remote access)
  • OAuth token auto-refresh — never worry about expiry mid-session
  • Docker support — one-command deployment
  • Hermes Agent skill included — see skills/cor-mcp-setup/
  • 24 passing tests — fully mocked, no live credentials required

Entity Coverage

Module Tools Covers
Projects 14 CRUD, collaborators, costs, labels, ratecards, templates, profitability
Tasks 10 Search, CRUD, collaborators, labels
Team & Users 8 Profile, users, teams, working time
Clients 6 CRUD, fees
Contracts 5 CRUD, positions
Time Tracking 5 Log, search, status, accept suggested
Messaging 4 Project + task messages
Allocations 3 CRUD
Ratecards 3 CRUD
Products 2 CRUD
Labels 1 By entity type

🚀 Quick Start

Prerequisites

  • Python 3.11+
  • uv (recommended) or pip
  • COR account with credentials

Install & Run

# Clone
git clone https://github.com/fxckcode/mcp-cor.git
cd mcp-cor

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

Configure

cp .env.example .env

Then choose one auth mode in .env:

Mode A — Email + Password (recommended for personal use)

COR_EMAIL=your.email@company.com
COR_PASSWORD=your_password
COR_API_URL=https://api.projectcor.com/v1

Mode B — API Key + Client Secret (for server-to-server)

COR_API_KEY=your_api_key
COR_CLIENT_SECRET=your_client_secret
COR_API_URL=https://api.projectcor.com/v1

The server auto-detects which mode you configured. Email/password takes priority when both are set.

Run

# stdio transport (default — for MCP agents)
uv run cor-mcp-server

# SSE/HTTP transport (for remote access)
uv run cor-mcp-server --transport sse --host 0.0.0.0 --port 8000

# Verbose logging
uv run cor-mcp-server --verbose

🔐 Authentication

Two modes supported. The server auto-detects which to use.

User Credentials (Mode A)

POST https://api.projectcor.com/v1/auth/login
Content-Type: application/x-www-form-urlencoded

email=user@corp.com&password=*****

Returns JWT access_token + refresh_token. Auto-refresh built in.

Client Credentials (Mode B)

POST https://api.projectcor.com/v1/oauth/token?grant_type=client_credentials
Authorization: Basic base64(api_key:client_secret)

Returns access_token (1-hour TTL). Cached and auto-refreshed with a 60-second safety margin.

🔌 Connecting from MCP Clients

Hermes Agent (recommended) — click to expand

Add to ~/.hermes/config.yaml:

mcp_servers:
  cor:
    command: "uv"
    args: ["run", "--directory", "/path/to/cor-mcp-server", "python", "-m", "cor_mcp_server"]
    env:
      COR_EMAIL: "your.email@company.com"
      COR_PASSWORD: "your_password"
      COR_API_URL: "https://api.projectcor.com/v1"
    timeout: 180
    connect_timeout: 60

Then restart or run /reload-mcp.

Claude Desktop — click to expand

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cor": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/cor-mcp-server", "python", "-m", "cor_mcp_server"],
      "env": {
        "COR_EMAIL": "your.email@company.com",
        "COR_PASSWORD": "your_password",
        "COR_API_URL": "https://api.projectcor.com/v1"
      }
    }
  }
}
Cursor / Windsurf / Cline — click to expand

In MCP Servers settings, add:

  • Name: COR
  • Type: command
  • Command: uv run --directory /path/to/cor-mcp-server python -m cor_mcp_server
  • Environment variables: COR_EMAIL, COR_PASSWORD, COR_API_URL
Claude Code — click to expand 
env COR_EMAIL=your@email.com COR_PASSWORD=your_pass COR_API_URL=https://api.projectcor.com/v1 \
  npx @anthropic/claude-code --mcp "uv run --directory /path/to/cor-mcp-server python -m cor_mcp_server"

Docker

docker build -t cor-mcp-server .

# stdio mode
docker run -i --rm \
  -e COR_EMAIL=your@email.com \
  -e COR_PASSWORD=your_password \
  -e COR_API_URL=https://api.projectcor.com/v1 \
  cor-mcp-server

# SSE mode
docker run -i --rm \
  -p 8000:8000 \
  -e COR_EMAIL=your@email.com \
  -e COR_PASSWORD=your_password \
  -e COR_API_URL=https://api.projectcor.com/v1 \
  cor-mcp-server --transport sse

🛠 Available Tools

All tool names are prefixed with cor_ for clean discoverability.

Projects (14 tools)

Tool Description
cor_list_projects List projects with filters (clientId, status, health, dates)
cor_get_project Get project details
cor_create_project Create a new project
cor_update_project Update a project (partial)
cor_delete_project Delete a project
cor_get_project_collaborators Get project collaborators
cor_add_project_collaborator Add collaborator to project
cor_remove_project_collaborator Remove collaborator from project
cor_get_project_costs Get project costs/estimates
cor_add_project_cost Add cost to project
cor_get_project_labels Get project labels
cor_get_project_ratecard Get project ratecard
cor_get_project_templates Get available project templates
cor_get_project_profitability Get project profitability

Tasks (10 tools)

Tool Description
cor_search_tasks Search tasks with filters (projectId, clientId, status, text, dates, labels)
cor_get_my_pending_tasks Get my pending tasks
cor_get_task Get task details
cor_create_task Create a new task
cor_update_task Update a task
cor_delete_task Delete a task
cor_get_task_collaborators Get task collaborators
cor_sync_task_collaborators Sync (replace) task collaborators
cor_add_task_label Add label to task
cor_remove_task_label Remove label from task

Team & Users (8 tools)

Tool Description
cor_get_my_profile Get current user profile
cor_list_users List users with filters
cor_get_user Get user details
cor_list_teams List teams
cor_create_team Create a new team
cor_add_team_users Add users to a team
cor_remove_team_users Remove users from a team
cor_get_working_time Get working time for users

Clients (6 tools)

Tool Description
cor_list_clients List clients
cor_get_client Get client details
cor_create_client Create a new client
cor_update_client Update a client
cor_delete_client Delete a client
cor_get_client_fees Get client fees

Contracts (5 tools)

Tool Description
cor_list_contracts List contracts
cor_get_contract Get contract details
cor_create_contract Create a new contract
cor_get_contract_positions Get contract positions
cor_create_contract_position Create position in contract

Time Tracking (5 tools)

Tool Description
cor_log_hours Log hours against a task
cor_search_time_entries Search time entries with filters
cor_get_hours_by_date Get time entries by date
cor_change_hours_status Change time entry status
cor_accept_suggested_hours Accept suggested hours

Messaging (4 tools)

Tool Description
cor_get_task_messages Get messages on a task
cor_post_task_message Post a message on a task
cor_get_project_messages Get messages on a project
cor_post_project_message Post a message on a project

Ratecards (3 tools)

Tool Description
cor_list_ratecards List ratecards
cor_get_ratecard Get ratecard details
cor_create_ratecard Create a new ratecard

Allocations (3 tools)

Tool Description
cor_get_allocations_by_project Get allocations for a project
cor_save_allocation Create/update a resource allocation
cor_delete_allocation Delete a resource allocation

Products (2 tools)

Tool Description
cor_list_products List products
cor_create_product Create a new product

Labels (1 tool)

Tool Description
cor_get_labels Get labels (filter by entity type: project, task, user)

🏗 Architecture

┌──────────────────────┐     ┌───────────────────────────┐     ┌──────────────────────┐
│  MCP Client          │     │  COR MCP Server           │     │  COR REST API        │
│  (Hermes / Claude /  │◄───►│  (FastMCP + httpx)        │────►│  api.projectcor.com  │
│   Cursor / etc.)     │     │                            │     │  /v1                 │
└──────────────────────┘     ├───────────────────────────┤     └──────────────────────┘
                             │  Auth auto-detection       │
                             │  • Email/Password (prio)   │
                             │  • API Key + Secret        │
                             └───────────────────────────┘

🧑‍💻 Development

# Install dev deps
uv sync --dev

# Run tests (24 passing tests — no live API needed, uses mocking)
uv run pytest tests/ -v

# Test server startup
uv run cor-mcp-server --help

# Lint
uv run ruff check .

Adding New Tools

To add a new tool to the COR MCP Server:

  1. Create or edit a tool module in cor_mcp_server/tools/ (e.g., reports.py).

  2. Write an async function with the cor_ prefix pattern:

    from ..context import get_client

async def cor_list_reports(page: int = 1, per_page: int = 20) -> str:
    """List reports.

    Args:
        page: Page number (default: 1)
        per_page: Results per page (default: 20)
    """
    client = get_client()
    data = await client.get("/reports", page=page, per_page=per_page)
    import json
    return json.dumps(data, indent=2, ensure_ascii=False, default=str)

  3. Register the tool in cor_mcp_server/server.py:

    from .tools import reports as _reports

mcp.tool(
    name="cor_list_reports",
    description=_reports.cor_list_reports.__doc__,
)(_reports.cor_list_reports)

  4. Add tests in tests/test_tools.py following the existing patterns (import assertion + tool count update).

  5. Update the tool count in tests/test_tools.py if needed.

The get_client() function provides a fully-authenticated CORClient instance with automatic Bearer token handling. All tools return JSON strings for consistent serialization.

Test Structure

Tests are in tests/test_tools.py and cover:

  • TestTokenStore — Thread-safe token caching, expiry, and refresh logic
  • TestCORClient — HTTP methods (GET, POST, PUT, DELETE), pagination, auth headers
  • TestToolFunctions — Import verification for all 61 tool functions across 11 modules
  • TestServerCreation — Server factory creates a valid FastMCP instance

All tests use mocking — no live COR credentials required to run them.

📁 Project Structure

cor-mcp-server/
├── pyproject.toml              # Dependencies and metadata
├── README.md                   # This file
├── LICENSE                     # MIT license
├── .env.example                # Env var template (both auth modes)
├── Dockerfile                  # Container deployment
├── skills/                     # Hermes Agent skills
│   └── cor-mcp-setup/
│       └── SKILL.md            # Skill: setup + usage guide
├── handoff-personal-hermes.md  # Self-contained instructions for personal Hermes
├── cor_mcp_server/
│   ├── __init__.py             # Package init
│   ├── __main__.py             # CLI entry point
│   ├── server.py               # FastMCP server + tool registration (all 61 tools)
│   ├── auth.py                 # OAuth 2.0 dual-mode (user creds + client creds)
│   ├── client.py               # COR API HTTP client (httpx, async)
│   ├── context.py              # Shared client context / dependency injection
│   ├── models.py               # Pydantic models (14 entity types)
│   └── tools/
│       ├── __init__.py
│       ├── projects.py         # 14 tools
│       ├── tasks.py            # 10 tools
│       ├── time_tracking.py    # 5 tools
│       ├── clients.py          # 6 tools
│       ├── contracts.py        # 5 tools
│       ├── messaging.py        # 4 tools
│       ├── team.py             # 8 tools
│       ├── labels.py           # 1 tool
│       ├── ratecards.py        # 3 tools
│       ├── allocations.py      # 3 tools
│       └── products.py         # 2 tools
├── tests/
│   ├── __init__.py
│   └── test_tools.py           # 24 tests for auth, client, and tools
├── .github/                    # GitHub community files
│   ├── dependabot.yml          # Dependency auto-updates
│   ├── ISSUE_TEMPLATE/         # Bug report + feature request templates
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── workflows/              # CI + Release pipelines
├── .gitignore
├── .gitattributes
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
└── SECURITY.md

📄 License

MIT

👤 Author

Alejandro Duran — Omnicom Media Group

About

MCP server for Project COR — 61 tools across 11 modules: projects, tasks, clients, contracts, time tracking, team management, messaging, and more

www.projectcor.com

Topics

python async mcp project-management cor model-context-protocol mcp-server fastmcp project-cor

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages