Teamdesk Mcp V2

TeamDesk MCP Server

MCP (Model Context Protocol) server for TeamDesk databases. Connects Claude (web, Desktop, and mobile), Claude Code, or any MCP-compatible client to the TeamDesk REST API v2.

Features

• 11 tools covering all TeamDesk CRUD operations + search + document generation
• Works with any TeamDesk database — just provide your token and database ID
• Two deployment modes:
• Local (server.py) — runs on user's machine via stdio
• Remote (deploy/server_sse.py) — multi-user server with OAuth 2.0, Streamable HTTP, rate limiting, and caching
• Correct URL encoding for accented table/column names (Portuguese, Spanish, etc.)
• Timeout handling with automatic retry (55s timeout, 2 retries with backoff)
• Filter injection prevention via input sanitization
• Stderr logging for request timing and debugging

Requirements

• Python 3.10+
• A TeamDesk REST API token (generate at: TeamDesk > Setup > Integration > REST API > Tokens)
• Your TeamDesk Database ID (visible in the TeamDesk URL: teamdesk.net/secure/db/XXXXX)

Installation

Option 1: Remote Connector (Recommended)

No local installation required. Connect directly from claude.ai — works on web, Desktop, and mobile automatically.

> When you add a custom connector on claude.ai, it syncs to Claude Desktop and mobile automatically. One setup covers all platforms.

1. Ask your admin to create an access key (see [Remote Deployment](#remote-deployment))
2. Go to claude.ai > Settings > Integrations > Add Custom Connector
3. Enter a name (e.g., TeamDesk) and the server URL: https://your-server.com/m/{your_key}/sse
4. Click Configure > approve access
5. Done — works on web, Desktop, and mobile

Option 2: Local Installer (Windows)

1. Download install.bat, server.py, and requirements.txt from this repo
2. Place them in the same folder
3. Run install.bat
4. Follow the prompts (it will ask for your token and database ID)
5. Restart Claude Desktop

Option 3: Local Installer (Linux / Mac)

1. Clone and run:

git clone https://github.com/Danielbluz/teamdesk-mcp-v2.git
cd teamdesk-mcp-v2
bash install.sh

1. Follow the prompts
2. Restart Claude Desktop

Option 4: Manual Setup

git clone https://github.com/Danielbluz/teamdesk-mcp-v2.git
cd teamdesk-mcp-v2
pip install -r requirements.txt

Then add to your client config (see next section).

Configuration

Claude Desktop (local mode)

Edit claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "teamdesk": {
      "command": "python",
      "args": ["C:\\path\\to\\server.py"],
      "env": {
        "TEAMDESK_API_TOKEN": "your_token_here",
        "TEAMDESK_DATABASE_ID": "your_database_id"
      }
    }
  }
}

Claude Code

Add to .claude/.mcp.json in your project or ~/.claude/.mcp.json globally:

{
  "mcpServers": {
    "teamdesk": {
      "command": "python",
      "args": ["C:\\path\\to\\server.py"],
      "env": {
        "TEAMDESK_API_TOKEN": "your_token_here",
        "TEAMDESK_DATABASE_ID": "your_database_id"
      }
    }
  }
}

Alternative: .env file

Instead of setting env vars in the config, you can create a .env file next to server.py:

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

Tools

| Tool | Description | |------|-------------| | list_tables | List all tables in the database | | describe_table | Get table structure (columns, types, properties) | | get_records | Query records with filters, sort, and pagination | | get_record | Retrieve a single record by ID | | select_view | Query records from a pre-configured View | | create_record | Create a new record | | update_record | Update an existing record by ID | | delete_record | Delete a record by ID | | search_records | Full-text search across text columns (auto-detected) | | upsert_records | Insert or update records (match column must be Unique) | | gerar_documento | Generate a DOCX from a TeamDesk Documents template |

Filter Examples

[Status] = 'Ativo'
[Amount] > 1000
Contains([Name], 'Solar')
[Date] >= ToDate('2026-01-01')

Sort Syntax

Column          -- ascending (default)
Column//DESC    -- descending

TeamDesk API Quirks

These are undocumented behaviors that this server handles correctly:

| Quirk | Detail | |-------|--------| | DELETE uses GET | {table}/delete.json?id={id} is a GET request | | UPDATE uses POST | Not PUT. Body must include @row.id | | Body must be array | All write operations require [{...}], not {...} | | Upsert match must be Unique | Match column must be marked Unique in table setup, otherwise error 3106 | | Document endpoint has no .json | Use /document?id=X, not /document.json?id=X | | Sort uses // | Column//DESC, not -Column or Column DESC | | Accented names are valid | Geração, Irradiação — must be URL-encoded, not stripped | | No LIKE operator | Use Contains([field], 'value') (case-insensitive) | | Date literals use # | [Date] >= #2026-01-01# or ToDate('2026-01-01') | | Retrieve by ID | Use retrieve.json?id=X, not {id}.json |

Troubleshooting

MCP not appearing in Claude Desktop

• Make sure you restarted Claude Desktop completely (check system tray)
• Verify python is in your PATH: python --version
• Check the config JSON syntax (no trailing commas)

Slow responses

• TeamDesk servers can be slow during US business hours (15:00–18:00 UTC)
• The server retries automatically on timeout (up to 2 times)
• Check logs: Claude Desktop > Ctrl+Shift+I > Console > filter [TeamDesk MCP]

Token issues

• Generate a new token at: TeamDesk > Setup > Integration > REST API > Tokens
• The token should be a 32-character hex string
• Both TEAMDESK_API_TOKEN and TEAMDESK_TOKEN (legacy) are accepted

Remote Deployment

The deploy/ folder contains server_sse.py — a multi-user remote MCP server designed for deployment on a VPS behind Nginx/TLS. It supports:

• OAuth 2.0 with auto-approve (PKCE S256) — required by claude.ai custom connectors
• Streamable HTTP transport (MCP SDK 1.26.0+) — the protocol claude.ai uses
• SSE transport — for Claude Desktop local config via URL
• Multi-user authentication via API keys stored in a TeamDesk table
• Rate limiting and response caching
• Per-user tokens — each user's API key maps to their own TeamDesk token

How it works

1. Admin creates a record in the Acesso table (TeamDesk) with:

• Chave_MCP: unique key for the user (e.g., john_company_2026)
• Token: the user's TeamDesk API token
• Ativo_MCP: Sim (to enable access)

1. Each user gets a personal endpoint: https://your-server.com/m/{chave}/sse

1. The server validates the key, retrieves the user's token, and proxies all MCP tool calls to the TeamDesk API using that token.

OAuth 2.0 endpoints

claude.ai requires these OAuth endpoints for custom connectors:

| Endpoint | Purpose | |----------|---------| | /.well-known/oauth-protected-resource | RFC 9728 — resource metadata | | /.well-known/oauth-authorization-server | RFC 8414 — auth server metadata | | /register | RFC 7591 — dynamic client registration | | /authorize | Authorization endpoint (auto-approve) | | /token | Token exchange (PKCE S256 verification) |

Technical notes

• claude.ai uses POST (Streamable HTTP), not GET (SSE) — the server handles both
• The server injects the Accept: application/json, text/event-stream header if missing (claude.ai sometimes omits it, causing 406 from MCP SDK)
• Sessions are stateful (stateless=False) — required for persistent Mcp-Session-Id
• Configure via environment variables (see deploy/docker-compose.yml)

Docker deployment

cd deploy
cp .env.example .env
# Edit .env with your TEAMDESK_DATABASE_ID, TEAMDESK_MASTER_TOKEN, MCP_PUBLIC_URL
docker compose up -d

Key discovery: web = Desktop = mobile

When a user configures a custom connector on claude.ai (web), it automatically becomes available on Claude Desktop and Claude mobile — no separate configuration needed. The connector is linked to the user's Anthropic account, not to a specific app.

This means: one setup on the web covers all platforms.

Security

• Tokens are read from environment variables, never hardcoded
• Filter injection prevented by escaping single quotes
• Table names are URL-encoded to preserve accented characters
• API keys validated against TeamDesk table (not hardcoded)
• OAuth auto-approve uses PKCE S256 for security
• Rate limiting prevents abuse (configurable per-minute limit)
• See [SECURITY.md](SECURITY.md) for responsible disclosure

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Danielbluz
• Source: Danielbluz/teamdesk-mcp-v2
• License: MIT

Install and usage instructions live in the source repository linked above.