MCP DevTools

mcp-devtools

AI-native developer tools via [Model Context Protocol](https://spec.modelcontextprotocol.io).

A production-grade MCP server that gives AI agents (Claude, Cursor, Copilot, Continue, ...)

safe, scoped access to your local development environment.

Why

The MCP ecosystem is full of single-purpose tutorials and vendor-locked adapters. There is no well-maintained, multi-tool, framework-agnostic, production-quality MCP package for everyday developer tooling.

mcp-devtools fills that gap with 14 tools, 3 MCP Resources, 4 MCP Prompts, a Plugin API, two transport modes (stdio + HTTP with auth), and an audit log — built on patterns refined in production at DailyBot.

Quick start

stdio (default)

npx @oscarmarin/mcp-devtools

Add it to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{

"mcpServers": { "devtools": { "command": "npx", "args": ["-y", "@oscarmarin/mcp-devtools"] } } }

Or Cursor (~/.cursor/mcp.json): same block.

HTTP transport

Create a mcp-devtools.json in your project root:

{

"transport": "http", "port": 3333, "auth": { "token": "env:MCP_AUTH_TOKEN" } }

Then start the server:

npx @oscarmarin/mcp-devtools

The MCP endpoint will be available at http://localhost:3333.

Tools

Per-tool reference: docs/tools/.

MCP Resources

The server exposes read-only data via MCP Resources:

MCP Prompts

Curated prompt templates for common development workflows:

Plugin API

Extend mcp-devtools with custom tools — no fork required.

Config-based (load at startup):

{

"plugins": ["./my-tools.js", "@scope/mcp-plugin-foo"] }

Each plugin module default-exports an array of tool definitions:

import { defineTool } from "@oscarmarin/mcp-devtools";

import { z } from "zod";

export default [ defineTool({ name: "my_tool", description: "Does something useful", inputSchema: z.object({ input: z.string() }), handler: async (args, config) => ({ ok: true, data: { result: args.input.toUpperCase() }, }), }), ];

Configuration

Configuration is loaded by cosmiconfig from mcp-devtools.json, .mcp-devtoolsrc, or the mcpDevtools key in package.json. See mcp-devtools.example.json and docs/configuration.md for the full schema.

Zero-config is supported: running npx @oscarmarin/mcp-devtools with no config uses schema defaults (RNF-05).

Security

Four non-bypassable controls:

1. Filesystem scope boundary. Every path is resolved to an absolute and compared against config.scope. Symlinks that escape scope throw SCOPE_VIOLATION.
2. Command allowlist. run_command only executes binaries whose basename is in allowedCommands. Invocation uses spawn(file, args) (no shell), so shell-injection via the command argument is structurally impossible.
3. Database read-only mode. When readOnly: true, all SQL is parsed and INSERT/UPDATE/DELETE/DROP/CREATE/GRANT are rejected. Queries run in BEGIN READ ONLY ... ROLLBACK on PostgreSQL.
4. HTTP Bearer auth. When auth.token is configured, every HTTP request must include Authorization: Bearer . Comparison uses crypto.timingSafeEqual to prevent timing attacks.

Additional safety measures:

• Audit log. Opt-in NDJSON log of every tool invocation with timing, sanitized inputs, and result status.
• Secret masking. get_env automatically masks values matching common secret patterns (SECRET, TOKEN, PASSWORD, KEY, etc.).
• OpenAPI host restriction. call_api only sends requests to hosts listed in the spec's servers array.
• Output capping. All tools cap their output to prevent context flooding (100KB for commands, 1MB for files, 200 rows for queries).

Contributing

git clone https://github.com/marin1321/mcp-devtools.git

cd mcp-devtools npm install npm run dev # tsup --watch npm run test # vitest npm run typecheck # tsc --noEmit npm run lint # eslint .

See CONTRIBUTING.md for the full workflow and CODE_OF_CONDUCT.md for community guidelines.

License

MIT © Oscar Humberto Marin Molina — oscarmarindev.com