⬡ COR MCP Server

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

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: 180connect_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:

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

Write an async function with the cor_ prefix pattern:

from ..contextimportget_clientasyncdefcor_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=awaitclient.get("/reports", page=page, per_page=per_page)
importjsonreturnjson.dumps(data, indent=2, ensure_ascii=False, default=str)

Register the tool in cor_mcp_server/server.py:

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

Add tests in tests/test_tools.py following the existing patterns (import assertion + tool count update).
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

Navigation Menu

Repository files navigation

⬡ COR MCP Server

✨ Features

Entity Coverage

🚀 Quick Start

Prerequisites

Install & Run

Configure

Run

🔐 Authentication

User Credentials (Mode A)

Client Credentials (Mode B)

🔌 Connecting from MCP Clients

Docker

🛠 Available Tools

Projects (14 tools)

Tasks (10 tools)

Team & Users (8 tools)

Clients (6 tools)

Contracts (5 tools)

Time Tracking (5 tools)

Messaging (4 tools)

Ratecards (3 tools)

Allocations (3 tools)

Products (2 tools)

Labels (1 tool)

🏗 Architecture

🧑‍💻 Development

Adding New Tools

Test Structure

📁 Project Structure

📄 License

👤 Author

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
cor_mcp_server		cor_mcp_server
skills		skills
tests		tests
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
handoff-personal-hermes.md		handoff-personal-hermes.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

⬡ COR MCP Server

✨ Features

Entity Coverage

🚀 Quick Start

Prerequisites

Install & Run

Configure

Run

🔐 Authentication

User Credentials (Mode A)

Client Credentials (Mode B)

🔌 Connecting from MCP Clients

Docker

🛠 Available Tools

Projects (14 tools)

Tasks (10 tools)

Team & Users (8 tools)

Clients (6 tools)

Contracts (5 tools)

Time Tracking (5 tools)

Messaging (4 tools)

Ratecards (3 tools)

Allocations (3 tools)

Products (2 tools)

Labels (1 tool)

🏗 Architecture

🧑‍💻 Development

Adding New Tools

Test Structure

📁 Project Structure

📄 License

👤 Author

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages