Podio MCP Server

A Model Context Protocol (MCP) server that integrates Podio with Claude, enabling natural language management of Podio items and tasks. Automate workflows, manage projects, and organize work with conversational AI.

Features

• OAuth2 Authentication - Secure authentication with automatic token refresh
• CRUD Operations - Create, read, update, and delete Podio items and tasks
• Intelligent Caching - App structure caching with automatic refresh for performance
• AI-Powered Suggestions - Smart project/epic suggestions using fuzzy matching
• Multi-Workspace Support - Works with any Podio workspace using explicit coordinates
• Comprehensive Search - Search items, tasks, files, and conversations across scopes
• Notification Management - Manage and filter Podio notifications
• Activity Tracking - Full comment and revision history for items
• Robust Error Handling - Detailed error messages for debugging

Tech Stack

| Layer | Technology | |-------|-----------| | Runtime | Node.js 24+ / Bun | | Language | TypeScript 5.9+ | | Protocol | Model Context Protocol SDK ^0.7.0 | | Testing | Jest 30 | | Code Quality | Biome 2.3+ (linting & formatting) | | Documentation | TypeDoc | | Package Manager | npm / Bun |

Prerequisites

• Node.js ≥ 24.0.0 or Bun ≥ 1.0.0
• Podio account with API credentials (see Setup Guide)
• MCP-compatible client (Claude Desktop, Cline, etc.)

Quick Start

Install

bunx @forumviriumhelsinki/podio-mcp

Configure

Add to your MCP client configuration (.mcp.json or Claude Desktop config):

{
  "mcpServers": {
    "podio-mcp": {
      "command": "bunx",
      "args": ["@forumviriumhelsinki/podio-mcp"],
      "env": {
        "PODIO_CLIENT_ID": "${PODIO_CLIENT_ID}"
      }
    }
  }
}

This uses Podio's implicit OAuth flow, which only needs a Client ID. To use the auth-code flow instead, add PODIO_CLIENT_SECRET to the env block. PODIO_REDIRECT_URI is optional — the published package bakes in http://localhost:8080/callback; override it only if your Podio app is registered with a different redirect URI.

Claude Code one-liner

Register the server at project scope so credentials stay in .mcp.json rather than ~/.claude.json. The single-quoted <<'EOF' delimiter keeps the ${VAR} references literal — Claude Code expands them at spawn time, so no secrets are written to disk:

claude mcp add-json --scope project podio-mcp "$(cat <<'EOF'
{
  "command": "bunx",
  "args": ["-y", "@forumviriumhelsinki/podio-mcp"],
  "env": {
    "PODIO_CLIENT_ID": "${PODIO_CLIENT_ID}"
  }
}
EOF
)"

After running, verify the file contains the literal placeholder, not an expanded value:

grep PODIO_CLIENT_ID .mcp.json
# Expected: "PODIO_CLIENT_ID": "${PODIO_CLIENT_ID}"

Add -s user before the name to install at user scope (~/.claude.json) instead. Drop any PODIO_* lines you don't have set — empty strings would otherwise overwrite the package's baked-in defaults.

Get your API credentials from Podio Developers.

Usage Examples

# Load an app structure for querying
Load app structure for myorg/myspace/myapp

# Query items with filters
Show me all items with status "In Progress"

# Create new items
Create a new item titled "Review pull request" with description "Urgent PR"

# Search across workspace
Search for items containing "authentication" in myspace

# Manage tasks
Create a task assigned to [email protected] due tomorrow

# Get notifications
Show my unread notifications from the last 7 days

See Usage Examples for more detailed workflows.

Project Structure

podio-mcp/
├── src/
│   ├── index.ts                 # Main MCP server
│   ├── oauth-helper.ts          # OAuth2 authentication
│   ├── api/
│   │   └── podio-api-client.ts  # Podio HTTP client
│   ├── services/                # Business logic layer
│   │   ├── items/               # Item CRUD operations
│   │   ├── tasks/               # Task management
│   │   ├── comments/            # Comment handling
│   │   ├── search/              # Search functionality
│   │   ├── app/                 # App structure discovery
│   │   ├── notifications/       # Notification management
│   │   └── project-epic/        # Project/epic suggestions
│   ├── handlers/                # Tool-call handlers extracted from index.ts
│   ├── tools/                   # Tool schemas / registration
│   ├── fields/                  # Podio field-shape converters
│   ├── cache/                   # Caching layer
│   ├── config/                  # Build-time defaults injected at publish
│   ├── errors/                  # Custom error types
│   ├── utils/                   # Cross-cutting helpers
│   └── types/                   # TypeScript definitions
├── __tests__/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── fixtures/                # Test data and mocks
├── docs/                        # Documentation
├── scripts/                     # Build and configuration scripts
└── build/                       # Compiled output (generated)

Development

Build & Run

# Development with watch mode
bun run dev

# Build production bundle
bun run build

# Run the server
bun run start

# Generate configuration
bun run configure

Code Quality

# Lint with Biome
bun run lint

# Auto-fix lint issues
bun run lint:fix

# Format code
bun run format

# Check formatting
bun run format:check

# Run all checks (CI mode)
bun run check

Testing

# Run all tests
bun test

# Run with coverage report
bun run test:coverage

# Watch mode for development
bun run test:watch

# Unit tests only
bun run test:unit

# Integration tests only
bun run test:integration

Documentation

# Generate TypeDoc API documentation
bun run docs

# Watch mode with live reload
bun run docs:serve

# Build everything including docs
bun run docs:build

# Deploy documentation
bun run docs:deploy

Documentation

• Setup Guide - Installation, configuration, and troubleshooting
• Usage Examples - Commands and workflow patterns
• API Documentation - Architecture and API details
• Notifications Guide - Notification management
• Live Docs - Generated API reference

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | PODIO_CLIENT_ID | Podio API Client ID | Yes (the published package bakes in a default; override for your own Podio app) | | PODIO_CLIENT_SECRET | Podio API Client Secret | No (presence enables auth-code flow; absence selects implicit flow) | | PODIO_REDIRECT_URI | OAuth redirect URI | No (defaults to http://localhost:8080/callback) | | PODIO_DEBUG | Enable debug logging | No |

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/your-feature)
3. Write tests first (TDD approach) and implement functionality
4. Run the test suite (bun test) and check coverage
5. Format and lint your code (bun run format && bun run lint:fix)
6. Commit with conventional commits:
   • feat(scope): description - New features
   • fix(scope): description - Bug fixes
   • docs: description - Documentation changes
   • test: description - Test additions
   • chore: description - Maintenance
7. Push to your fork and submit a pull request

See the Testing Guide for detailed testing practices.

Troubleshooting

Encounter an issue? Check the Setup Guide Troubleshooting section or create an issue with:

• Error message and stack trace
• Steps to reproduce
• Environment (Node.js version, OS)
• MCP client being used

License

MIT License - see LICENSE for details.

Support

• Troubleshooting Guide
• GitHub Issues
• Podio API Documentation