# devto-mcp

**The work management layer for Claude Code.**

DevTo lives inside Claude Code as an MCP server. It manages your sprint, your tickets, and your project tracker — without you ever leaving your terminal. Status updates, ambient comments on transitions, plan generation from natural language, semantic ticket matching. All from your editor.

Today: full Jira Cloud support via one-click OAuth. Linear and GitHub Issues coming.

## Install

```bash
npx devto-mcp@latest --help
```

You don't need a global install. `devto init` writes a project-scoped `.mcp.json` that runs the latest published version via `npx` on each Claude Code session start.

Requires Node.js 18+ and [Claude Code](https://claude.ai/code).

## Setup

### 1. Create an account

Sign up at [devto.ai](https://devto.ai). Connect your Jira workspace from the onboarding screen — click **Connect with Jira** and approve the OAuth consent. No tokens to copy, no API keys to paste.

### 2. Link the project

In your project directory:

```bash
cd your-project
npx devto-mcp@latest devto init
```

A short verification code appears. The CLI opens your browser to `devto.ai/cli/authorize` — confirm the code matches, click **Approve**, and the CLI receives your API key silently.

`devto init` writes:

| File | Purpose |
|------|---------|
| `.devto.json` | Project metadata (workspace, project key, provider) |
| `.devto/config.json` | Local credentials (API key, scoped to this project) |
| `.mcp.json` | Claude Code MCP server config (npx command + env) |

`.devto/`, `.devto.json`, and `.mcp.json` are added to `.gitignore` automatically.

### 3. Restart Claude Code

MCP server configs load at session start. Quit Claude Code fully and reopen — `claude mcp list` should now show `devto`.

You're done. No Anthropic key required: AI planning runs through DevTo's backend at no per-call cost to you (subject to your plan's monthly action quota).

## Use it

Just talk to Claude Code about your work. The MCP guides Claude toward the right tools — you don't need to memorize them.

```
> what's in my current sprint?
> create a plan for adding Stripe webhooks
> mark the auth task as done and add a comment about the redirect fix
> show recent comments on JOB-22
```

DevTo's natural-language semantic matching means you can refer to tickets by description ("the login bug", "that auth task") instead of memorizing keys like `JOB-22`. Ambiguous matches surface a disambiguation prompt.

## Tools

44 MCP tools, grouped by area. Claude Code reads the full descriptions from the server at session start.

**Project overview**
- `get_project_summary` — lightweight snapshot of active work + epic progress (called at session start)
- `get_status` — aggregate project metrics
- `list_epics` — epic progress bars
- `get_epic` — deep dive into a single epic

**Planning**
- `create_plan` — AI-generated epic + stories + subtasks (preview only)
- `confirm_plan` — execute a previously-previewed plan

**Issue management**
- `create_epic`, `create_task`, `create_subtask` — direct creates
- `update_task`, `update_epic` — status, fields, comments. Accepts natural language refs.
- `delete_issue` — destructive, asks for confirmation
- `get_tasks` — list open tasks, optionally filter by epic

**Comments**
- `add_comment`, `get_comments`, `delete_comment`

**Sprint management**
- `list_sprints`, `create_sprint`, `move_to_sprint`, `manage_sprint`

**Search**
- `search_issues` — full JQL support

**Field discovery**
- `get_priorities`, `get_statuses`, `get_issue_types`, `get_labels`, `get_components`, `get_assignable_users`, `get_custom_fields`

**Issue linking**
- `link_issues`, `get_issue_links`, `get_link_types`

**Time tracking**
- `log_work`, `get_worklog`, `set_estimate`

**Versions / releases**
- `list_versions`, `create_version`, `release_version`

**Backlog**
- `get_backlog`, `move_to_backlog`

**Bulk operations**
- `bulk_create_tasks`, `bulk_update_tasks`

**Attachments**
- `attach_file`, `list_attachments`

**Watchers**
- `manage_watchers`

## CLI commands

| Command | What it does |
|---------|--------------|
| `devto login` | Authenticate globally (browser flow) |
| `devto init` | Link the current directory to a DevTo workspace |
| `devto status` | Show connection state + active project |
| `devto doctor` | Diagnostic — checks API key, workspace token, MCP registration, AI mode |
| `devto sync` | Re-fetch workspace config from devto.ai |
| `devto unlink` | Remove this project's link (keeps the package installed) |
| `devto config set anthropic-key <key>` | Optional Expert Mode — see below |

### Expert Mode (BYOK)

By default, DevTo's backend handles Anthropic calls for `create_plan`. If you'd rather use your own Anthropic key — for billing reasons, or because you have credits to burn — run:

```bash
devto config set anthropic-key sk-ant-xxxx
```

DevTo will detect the local key and call Anthropic directly from your machine instead of the server proxy. Your code context still never leaves your machine in either mode; the only thing that changes is who pays for the inference.

## Per-project configuration

Each project gets its own `.devto.json`:

```json
{
  "workspaceUrl": "https://yourcompany.atlassian.net",
  "projectKey": "ENG",
  "provider": "jira"
}
```

The MCP server walks up the directory tree from `cwd` looking for `.devto.json`. Found? That workspace + project apply. Not found? Falls back to the tenant's active workspace from the dashboard.

You can have many projects with different `.devto.json` files on the same machine. Each one is independent.

## Troubleshooting

**Claude Code doesn't see devto's tools**
1. Did you restart Claude Code after `devto init`? MCP configs load at session start, not live.
2. Run `claude mcp list` from the project directory. You should see `devto:` in the output.
3. Try `devto doctor` — it prints a complete diagnostic with green checkmarks or red Xs and a suggested fix for each.

**`OAUTH_REAUTH_REQUIRED` error mid-session**
Your Jira connection's OAuth token has expired or been revoked. Visit [devto.ai/dashboard/settings/workspace](https://devto.ai/dashboard/settings/workspace) and click **Reconnect**. Takes 10 seconds.

**Need to start over for a project**
`devto unlink` clears `.devto.json`, `.devto/`, the `devto` entry in `.mcp.json`, and the project's row in `~/.devto/projects.json`. Other projects are unaffected.

## Dashboard

Manage workspaces, API key sessions, billing, and team at [devto.ai/dashboard](https://devto.ai/dashboard).

## License

MIT — see [LICENSE](./LICENSE).