Podio MCP Server

A Model Context Protocol (MCP) server for Podio. Inspect APIs, authenticate, manage items/tasks/apps, and generate TypeScript field configs from Cursor, Claude Desktop, or any MCP-compatible client.

Features

• Consolidated Podio tools — items, apps/spaces, tasks, communication, search, metadata, system

• Generic API caller — call any catalogued Podio endpoint via callPodioApi

• OAuth / app-token auth — organization- and app-level tokens

• API catalog — browse and search Podio endpoints

• HTTP/SSE mode — optional remote access (Docker / npm run start:http)

Related MCP server: Taskade MCP Server

Prerequisites

• Node.js 18+

• Podio account with API access

• An MCP client (e.g. Cursor, Claude Desktop)

Quick start (npm / npx)

Add to your MCP client config (e.g. Cursor .cursor/mcp.json):

{
  "mcpServers": {
    "podio-developer-mcp": {
      "command": "npx",
      "args": ["-y", "@phasesdk/mcp-server-for-podio"]
    }
  }
}

Create podio.config.json in the working directory the client uses for the server (often your project root):

cp podio.config.json.example podio.config.json
# edit clientId, clientSecret, apps

Restart the client, then verify with podio_system operation ping or get_config_status.

Install from source

git clone https://github.com/phases/mcp-server-for-podio.git
cd mcp-server-for-podio
npm install
npm run build

Point the client at the built entry:

{
  "mcpServers": {
    "podio-developer-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-for-podio/dist/index.js"]
    }
  }
}

Development

npm run build
npm run dev
npm start
npm run lint
npm run format

HTTP mode (landing page + SSE):

npm run start:http
# open http://localhost:3016/

Available tools

Most tools take an operation enum. Example: podio_system with { "operation": "ping" }.

Project structure

mcp-server-for-podio/
├── src/           # MCP server and tools
├── data/catalog/  # Podio API catalog (required at runtime)
├── dist/          # Compiled output
├── docs/          # Extra documentation
└── index.html     # HTTP landing page

Configuration

See CONFIGURATION.md. Required: clientId, clientSecret. Optional: username, password, apps[].

Secrets live in podio.config.json (gitignored). Never commit that file.

Deploy (HTTP / remote MCP)

Use this when clients connect over a URL (SSE), not local npx/stdio.

Endpoints

Run locally in HTTP mode

npm ci && npm run build
PORT=3016 BIND_ADDRESS=0.0.0.0 node dist/index.js
# or: npm run start:http

Create podio.config.json in the process working directory (copy from podio.config.json.example). Bind-mount it for Docker.

Docker

docker build -t mcp-server-for-podio .
docker run --rm -p 3016:3016 \
  -v "$PWD/podio.config.json:/app/podio.config.json:ro" \
  -e PORT=3016 \
  mcp-server-for-podio

Remote client config

{
  "mcpServers": {
    "podio-developer-mcp": {
      "url": "https://your-host.example/sse"
    }
  }
}

Production reverse proxy, TLS, systemd/PM2: see DEPLOYMENT.md.

Publish (GitHub + npm)

Package is ready to ship. From a clean tree after npm run build:

1. GitHub. The published branch is main on phases/mcp-server-for-podio. Do not push master.

git remote add github git@github.com:phases/mcp-server-for-podio.git   # first time only
git push -u github HEAD:main

2. npm (logged in as a member of the phasesdk org):

npm whoami
npm publish --access public

Bump version in package.json before republishing. prepublishOnly runs tsc automatically. Published tarball includes dist/, data/, index.html, and the example config (see files in package.json).

Landing page

In HTTP mode, GET / serves index.html with connect instructions.

Documentation

• Configuration

• Deployment — reverse proxy, TLS, systemd/PM2

• Cursor setup

• PRD

License

MIT

Contributing

Issues and PRs welcome once the GitHub repo is live: phases/mcp-server-for-podio.