devboard-mcp
v1.1.2
Published
MCP server for Devboard - enables AI agents to work on projects, boards, tasks, clients, and team with user-scoped access
Maintainers
Readme
Devboard MCP Server
MCP (Model Context Protocol) server for Devboard. Enables AI agents to work on projects, boards, tasks, clients, team members, and invoices with user-scoped access (data is limited to the logged-in user). A repo-local .devboard file feeds the AI with current project/board info every time.
Features
- User-scoped access: Recommended auth uses a durable
DEVBOARD_AGENT_TOKENthat the MCP server exchanges for a 60-minute JWT before calling Supabase. LegacyDEVBOARD_ACCESS_TOKENand email/password login remain available as fallback paths. - Local project context: A repo-local
.devboardJSON file holds current project id, board ids, user id, etc. Usedevboard-mcp init,devboard_get_context/devboard_set_context, and thedevboard://context/projectresource to feed the AI. - Standalone: Runs on its own with config via env (or
.env) to connect to your production Supabase backend. - Transports: stdio (default, for Cursor/IDE) or HTTP (Streamable HTTP).
Public npm usage
Run the CLI directly from npm without cloning the repository:
npx devboard-mcp auth login
npx devboard-mcp init
npx devboard-mcp mcp setupIf the package is ever published under a scoped fallback name, replace devboard-mcp with @devboard/devboard-mcp.
For MCP clients that spawn a command, the minimal stdio config is:
{
"mcpServers": {
"devboard": {
"command": "npx",
"args": ["-y", "devboard-mcp"]
}
}
}Run devboard-mcp auth login first so the server can reuse the saved local durable session. You only need DEVBOARD_HOST when targeting a non-default Devboard deployment.
Contributor quick start
1. Config (standalone / production)
Copy .env.example to .env and set:
# Optional: override the default hosted Devboard app
# DEVBOARD_HOST=https://your-devboard-host.netlify.app
# DEVBOARD_AGENT_TOKEN=dbat_your_agent_token
# Required only for direct token or email/password auth modes
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
# Legacy auth fallbacks:
# DEVBOARD_ACCESS_TOKEN=your-supabase-session-access-token
# [email protected]
# DEVBOARD_PASSWORD=your-passwordOptional:
CONTEXT_FILE_PATH– optional advanced override for the context file locationTRANSPORT=stdio(default) orTRANSPORT=httpPORT=3100– for HTTP transport
The server loads .env at runtime from the first matching locations (later files do not override earlier values):
DEVBOARD_ENV_FILE(explicit path)./.env(current working directory)../.envrelative to the running script (useful fordist/index.js)./dist/.env- macOS:
~/Library/Application Support/devboard-mcp/.env - Linux:
~/.config/devboard-mcp/.env
2. Install and build
cd mcp-server
npm install
npm run build3. Run
stdio (default, for Cursor/IDE):
npm start
# or: node dist/index.jsHTTP:
TRANSPORT=http PORT=3100 npm startThen open http://localhost:3100/mcp with an MCP client that supports Streamable HTTP.
4. Test with MCP Inspector
From the mcp-server directory:
npm run inspectorThis opens the MCP Inspector. Add a stdio server with:
- Command:
node - Args:
dist/index.js(or./dist/index.js)
Set env in the Inspector UI (or use a .env): DEVBOARD_AGENT_TOKEN (recommended) and optionally DEVBOARD_HOST if you are not using the default https://devboard-app.netlify.app. SUPABASE_URL and SUPABASE_ANON_KEY are only required for the legacy direct-token or email/password paths. Browser pairing also saves the durable token locally for later runs. Then list tools, call e.g. devboard_get_context or devboard_get_current_user, and read the devboard://context/project resource.
For HTTP, start the server in another terminal with TRANSPORT=http PORT=3100 npm start, then in the Inspector add an HTTP/Streamable HTTP server with URL http://localhost:3100/mcp.
Project context (local JSON)
Default behavior:
- The MCP server searches upward from the current working directory for
.devboard - If none exists, it targets
./.devboardin the current repo - You can override this with
CONTEXT_FILE_PATH
Repo linking
Run this once inside a repo to create .devboard and link that repo to a Devboard project:
devboard-mcp initinit now:
- offers browser login automatically if no local session exists
- lets you choose the repo-bound project and org scope
- writes
.devboardwithorg_id - can optionally generate exactly one
devboard-rule.mdin a folder such as.trae/rulesor.claude/rules - asks before overwriting an existing generated rule file
To change only the org binding later, run:
devboard-mcp context set-orgIf a project-scoped MCP tool runs before .devboard exists, the server returns a machine-readable linking error so the client can ask which project to link and then call devboard_bootstrap_project_context.
Example:
{
"project_id": "uuid",
"project_name": "My Project",
"org_id": "uuid",
"board_ids": ["uuid1", "uuid2"],
"current_board_id": "uuid1",
"user_id": "uuid",
"base_url": "https://app.devboard.example.com",
"last_updated": "2025-02-08T12:00:00.000Z",
"recent_project_ids": [],
"recent_board_ids": []
}- Tools:
devboard_get_context(read),devboard_set_context(update),devboard_bootstrap_project_context(populate after project selection). Use these so the AI always has current project/board info. - Resource:
devboard://context/project– same content as JSON; clients can read it as context.
Tools (summary)
| Tool | Description |
|------|-------------|
| devboard_login | Sign in with email + password; saves session to a local session file for all tools |
| devboard_get_context | Read local project context JSON |
| devboard_set_context | Update local project context |
| devboard_get_current_user | Get current user from access token / session |
| devboard_list_projects / devboard_get_project / devboard_create_project / devboard_update_project / devboard_delete_project | Projects CRUD |
| devboard_list_boards / devboard_get_board / devboard_create_board / devboard_update_board / devboard_delete_board | Boards CRUD |
| devboard_list_columns / devboard_create_column / devboard_update_column / devboard_delete_column | Board columns |
| devboard_list_tasks / devboard_get_task / devboard_create_task / devboard_update_task / devboard_delete_task | Board tasks |
| devboard_list_clients / devboard_get_client / devboard_create_client / devboard_update_client / devboard_delete_client | Clients CRUD |
| devboard_list_team_members / devboard_get_team_member / devboard_create_team_member / devboard_update_team_member / devboard_delete_team_member | Team members CRUD |
| devboard_list_invoices / devboard_get_invoice | Invoices (read-only list/get) |
All API tools use the user from the exchanged DEVBOARD_AGENT_TOKEN JWT, from DEVBOARD_ACCESS_TOKEN, or from the session file created by devboard_login / DEVBOARD_EMAIL + DEVBOARD_PASSWORD; RLS and backend rules apply.
Connecting to production
- Authenticate with
DEVBOARD_AGENT_TOKEN(recommended).DEVBOARD_HOSTdefaults tohttps://devboard-app.netlify.app; only set it if you use a different Devboard deployment. - For legacy direct-token or email/password paths, also set
SUPABASE_URLandSUPABASE_ANON_KEY. - Run the server (stdio or HTTP) as above.
The server does not start a Next.js app; in agent-token mode it bootstraps the active Supabase config from the Devboard exchange API.
Cursor / IDE (stdio)
- Add the server to your MCP config (e.g. Cursor MCP settings).
- Preferred public command:
npx -y devboard-mcp. - Local source checkout alternative:
node /path/to/devboard/mcp-server/dist/index.js(ornpm startfrommcp-server). - Ensure
DEVBOARD_AGENT_TOKENis set;DEVBOARD_HOSTis optional if you use the default hosted Devboard.SUPABASE_URLandSUPABASE_ANON_KEYare only needed for the legacy auth options (DEVBOARD_ACCESS_TOKEN, orDEVBOARD_EMAIL+DEVBOARD_PASSWORD)..envis loaded automatically from common locations.
Browser pairing (recommended)
If you run the Devboard web app on Netlify with the included pairing functions, you can authenticate the MCP server without copying tokens manually. The CLI now saves a durable agent token locally and exchanges it on demand.
- Create the
mcp_device_authorizationstable from supabase-schema.sql - Deploy the Netlify functions:
/.netlify/functions/mcpDeviceStart/.netlify/functions/mcpDeviceVerify/.netlify/functions/mcpDevicePoll
- From your machine:
npx devboard-mcp auth login --host https://YOUR_SITE.netlify.app- Open the printed URL, approve, and the CLI saves a durable agent token locally together with the authenticated identity metadata.
MCP client setup
npx devboard-mcp mcp setup
npx devboard-mcp mcp print cursor
npx devboard-mcp mcp print claude
npx devboard-mcp mcp print traemcp setup can write supported config files automatically:
- Cursor: project-local
.cursor/mcp.json - Trae: project-local
.trae/mcp.json - Claude Desktop: user-level
claude_desktop_config.json
Legacy devboard-mcp config <client> aliases still work.
Scripts
npm run build– compile TypeScript todist/npm start– rundist/index.js(stdio or HTTP fromTRANSPORT)npm run dev– run withtsx watchfor developmentnpm run clean– removedist/
