@devspeak/mcp

Official DevSpeak MCP server. Expose DevSpeak's technical translation engine as tools inside any MCP-compatible AI IDE or agent.

DevSpeak converts informal stakeholder requirements into formal, audience-specific technical specifications — Technical Specs, Jira Tickets, API Designs, RFCs, Data Models, and more.

Tools

| Tool | Description | | ------------------------ | ----------------------------------------------------------- | | translate_text | Translate informal input into a formal technical spec | | translate_markdown | Translate README / docs while preserving Markdown structure | | refine_translation | Iteratively refine generated output based on feedback | | detect_language | Detect the natural language of input text | | list_languages | Return supported natural languages | | auth_confirm | Verify API credentials against DevSpeak | | patch_translation_note | Surgically update a note in the DevSpeak Notes Workspace |

Prerequisites

1. A DevSpeak account at devspeak.dev
2. An API key — generate one from Settings → API Keys in the DevSpeak dashboard
3. Node.js 18 or later

Installation by IDE

Claude Code

Add to ~/.claude/settings.json (user-level) or .claude/settings.json (project-level):

{
  "mcpServers": {
    "devspeak": {
      "command": "npx",
      "args": ["-y", "-p", "@devspeak/mcp", "devspeak-mcp"],
      "env": {
        "DEVSPEAK_API_KEY": "dsk_live_YOUR_KEY_HERE"
      }
    }
  }
}

Or install the server globally and reference it directly:

npm install -g @devspeak/mcp

{
  "mcpServers": {
    "devspeak": {
      "command": "devspeak-mcp",
      "env": {
        "DEVSPEAK_API_KEY": "dsk_live_YOUR_KEY_HERE"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "devspeak": {
      "command": "npx",
      "args": ["-y", "-p", "@devspeak/mcp", "devspeak-mcp"],
      "env": {
        "DEVSPEAK_API_KEY": "dsk_live_YOUR_KEY_HERE"
      }
    }
  }
}

Cursor

Create or edit .cursor/mcp.json at the project root or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "devspeak": {
      "command": "npx",
      "args": ["-y", "-p", "@devspeak/mcp", "devspeak-mcp"],
      "env": {
        "DEVSPEAK_API_KEY": "dsk_live_YOUR_KEY_HERE"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "devspeak": {
      "command": "npx",
      "args": ["-y", "-p", "@devspeak/mcp", "devspeak-mcp"],
      "env": {
        "DEVSPEAK_API_KEY": "dsk_live_YOUR_KEY_HERE"
      }
    }
  }
}

VS Code (GitHub Copilot — Agent Mode)

Create .vscode/mcp.json at the workspace root:

{
  "servers": {
    "devspeak": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@devspeak/mcp", "devspeak-mcp"],
      "env": {
        "DEVSPEAK_API_KEY": "dsk_live_YOUR_KEY_HERE"
      }
    }
  }
}

Zed

Add to Zed's assistant.json (accessible via Zed → Settings → Assistant):

{
  "context_servers": {
    "devspeak": {
      "command": {
        "path": "npx",
        "args": ["-y", "-p", "@devspeak/mcp", "devspeak-mcp"],
        "env": {
          "DEVSPEAK_API_KEY": "dsk_live_YOUR_KEY_HERE"
        }
      }
    }
  }
}

Any MCP-compatible host (generic stdio config)

{
  "command": "npx",
  "args": ["-y", "-p", "@devspeak/mcp", "devspeak-mcp"],
  "env": {
    "DEVSPEAK_API_KEY": "dsk_live_YOUR_KEY_HERE",
    "DEVSPEAK_API_URL": "https://www.devspeak.dev"
  }
}

Environment Variables

| Variable | Required | Default | Description | | ------------------ | -------- | -------------------------- | ----------------------------------------------- | | DEVSPEAK_API_KEY | Yes | — | DevSpeak API key (dsk_live_… or dsk_test_…) | | DEVSPEAK_API_URL | No | https://www.devspeak.dev | Override for self-hosted or staging instances |

Usage Examples

Once installed, your AI agent can invoke DevSpeak tools directly:

Translate this rough spec into a formal Technical Spec for a Senior Dev:
"users should be able to log in with google and remember their session"

Translate the README at the path below for a Junior Dev audience, preserving all Markdown:
./README.md

Refine the previous output — make it more concise and remove the implementation details section.

Resources

The server also exposes three read-only resources your agent can fetch:

• devspeak://supported-languages — list of supported natural languages
• devspeak://api-reference — DevSpeak API surface summary
• devspeak://workflow-reference — the 3-stage Optimize → Translate → Refine workflow

Agent Skills

For guided, task-specific workflows (translate a README, translate docs, improve code comments, draft release notes), install the official DevSpeak Agent Skills:

• GitHub: devspeak-dev/devspeak-skills
• skills.sh: search devspeak

Skills require this MCP server to be installed and authenticated.

Links

• Platform: devspeak.dev
• CLI: @devspeak/cli on npm
• VS Code Extension: search DevSpeak in the VS Code Marketplace
• API Reference: devspeak.dev/docs
• Issues: github.com/devspeak-dev/devspeak-mcp/issues