debug MCP

MCP运维云端

提供方 Coykto

运维云端 stdio · 本地进程 Token 社区 / 第三方 Claude
查看接入方式

一个用于调试分布式系统的MCP服务器,支持AWS CloudWatch Logs、Step Functions、LangSmith和Jira等多种服务,通过单一网关工具提供17种调试功能。

一句话选型结论

按资料字段整理

debug MCP 属于运维云端类 MCP 服务器,stdio · 本地进程,Token,可直接接入 Claude,有可直接复制的远程端点配置。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式stdio · 本地进程 鉴权Token 部署方式支持远程部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

分布式系统Python本地部署调试工具AWSCloudWatchStepFunctionsLangSmith

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
uv run debug-mcp --aws-region us-west-2 --aws-profile your-profile

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    确认你的客户端支持远程端点,并拿到服务地址。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
debug MCP当前 未标注 stdio · 本地进程 支持远程部署 有 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方Coykto上游标注的维护方 Coykto
分类运维云端本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型支持远程部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

14.2 KB
来自项目仓库与上游目录的原文,未做删改

Debug MCP

MCP server for debugging distributed systems (AWS CloudWatch Logs, Step Functions, LangSmith, Jira) directly from Claude Code or any MCP client.

Status: ✅ Complete - Single gateway tool exposing 17 debugging tools
Context Reduction: ~95% token savings (13K → ~500 tokens)
Repository: https://github.com/Coykto/debug_mcp

Quick Start

Installation

Option 1: Using Claude Code CLI (Recommended)

AWS only:```bash
claude mcp add --scope user --transport stdio debug-mcp \
-- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
--aws-region us-west-2 \
--aws-profile your-aws-profile-name


AWS + Jira:```bash
claude mcp add --scope user --transport stdio debug-mcp \
    -- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
    --aws-region us-west-2 \
    --aws-profile your-aws-profile-name \
    --jira-host yourcompany.atlassian.net \
    --jira-email your.email@company.com \
    --jira-project PROJ \
    --jira-token your-api-token

Option 2: Manual configuration in .mcp.json

AWS only:```json
{
"mcpServers": {
"debug-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"--from", "git+https://github.com/Coykto/debug_mcp",
"debug-mcp",
"--aws-region", "us-west-2",
"--aws-profile", "your-aws-profile-name"
]
}
}
}


AWS + Jira:```json
{
  "mcpServers": {
    "debug-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/Coykto/debug_mcp",
        "debug-mcp",
        "--aws-region", "us-west-2",
        "--aws-profile", "your-aws-profile-name",
        "--jira-host", "yourcompany.atlassian.net",
        "--jira-email", "your.email@company.com",
        "--jira-project", "PROJ",
        "--jira-token", "your-api-token"
      ]
    }
  }
}

Note: Configuration is passed as CLI arguments to work around a known bug in Claude Code where environment variables aren't reliably passed to MCP servers.

Prerequisites:
- Python 3.11+
- uvx installed (installation guide)
- AWS credentials configured (aws configure)
- For Jira: API token from Atlassian (see Jira Configuration)

How to Use

Debug MCP exposes a single gateway tool called debug() that provides discovery and execution of 17 debugging tools:

Discovery Pattern

Ask Claude to discover available tools:```
"What debugging tools are available?"
→ Claude calls: debug(tool="list")

"What CloudWatch tools are available?"
→ Claude calls: debug(tool="list:cloudwatch")

"List all Step Functions tools"
→ Claude calls: debug(tool="list:stepfunctions")


### Execution Pattern

Ask Claude natural language questions and it will use the appropriate tool:

**CloudWatch Logs:**
- "List all Lambda log groups"
- "Search for ERROR in /aws/lambda/my-function from the last hour"
- "Analyze /aws/lambda/my-function logs for patterns"
- "Run a CloudWatch Insights query on my Lambda logs"

**Step Functions Debugging:**
- "List all my Step Functions state machines"
- "Show me the workflow definition and Lambda functions for state machine X"
- "Show me failed executions for state machine X from the last 3 days"
- "Get execution details including the workflow definition"
- "Find executions where the Match state output contains 'company' and show me the Lambda ARNs"

**LangSmith Tracing:**
- "List my LangSmith projects in prod environment"
- "Show me errored runs from the last hour in production"
- "Get details for LangSmith run abc-123 in dev"
- "Search for conversations containing a specific error message"

**Jira Tickets:**
- "Search for bugs in To Do status"
- "Find tickets assigned to me"
- "Get details for ticket PROJ-123"
- "Show me all in-progress stories about authentication"

Claude automatically translates your questions into the appropriate `debug()` call with the right tool name and arguments.

## How It Works

This MCP server uses a **Tool Discovery Gateway** pattern:

1. **Single Tool Interface**: Exposes one `debug()` tool to Claude instead of 17 individual tools
2. **~95% Token Reduction**: Reduces context from ~13K tokens to ~500 tokens (tool list only)
3. **Category-based Discovery**: Tools organized by category (cloudwatch, stepfunctions, langsmith, jira)
4. **Direct Implementation**: Uses boto3 and SDKs directly (no AWS MCP proxies)

### Gateway Architecture```
debug(tool="list")                     → List categories
debug(tool="list:cloudwatch")          → List CloudWatch tools
debug(tool="describe_log_groups", ...) → Execute tool

All 17 debugging tools remain available - they're just accessed through the gateway instead of being exposed individually.

Available Tools (via Gateway)

CloudWatch Logs (4 tools)

  • describe_log_groups - List CloudWatch log groups
  • analyze_log_group - Analyze logs for anomalies and patterns
  • execute_log_insights_query - Run CloudWatch Insights queries
  • get_logs_insight_query_results - Get query results

Step Functions (5 tools)

Debugging:
- list_state_machines - List all state machines (get ARNs)
- get_state_machine_definition - Get ASL definition with extracted Lambda ARNs and resources
- list_step_function_executions - List executions with filtering
- get_step_function_execution_details - Get full execution details with state inputs/outputs
- search_step_function_executions - Advanced search with state/input/output pattern matching

Definition & Resources:
The get_state_machine_definition tool extracts:
- Full Amazon States Language (ASL) workflow definition
- Lambda function ARNs used in the workflow
- Other resources (SNS topics, SQS queues, DynamoDB tables, nested state machines)
- IAM role, logging, and tracing configuration

You can also include the definition with execution details using include_definition=True in:
- get_step_function_execution_details - See the workflow definition alongside execution data
- search_step_function_executions - See definitions with filtered execution results

LangSmith (6 tools)

Tracing & Debugging:
- list_langsmith_projects - List available LangSmith projects
- list_langsmith_runs - List runs/traces with filtering (type, errors, time range)
- get_langsmith_run_details - Get full run details with inputs/outputs and child runs (stores in memory)
- search_langsmith_runs - Search for conversations containing specific text
- search_run_content - Semantic search within a stored run's content
- get_run_field - Get a specific field from a stored run

Multi-Environment Support:
Each LangSmith tool requires an environment parameter:
- prod - Uses PRODUCTION/env/vars from AWS Secrets Manager
- dev - Uses DEV/env/vars from AWS Secrets Manager
- local - Loads from .env file using python-dotenv

Credentials in Secrets Manager:
Your AWS Secrets Manager secret should contain:
- LANGCHAIN_API_KEY - Your LangSmith API key
- LANGCHAIN_PROJECT - Default project name (optional)

Local Development (.env file):```env
LANGCHAIN_API_KEY=ls_your_api_key_here
LANGCHAIN_PROJECT=your-project-name


> **Note**: LangSmith integration currently requires AWS Secrets Manager for `prod`/`dev` environments (this is how our team stores credentials). If you'd like to use LangSmith with direct CLI token arguments (similar to Jira), PRs are welcome!

### Jira (2 tools)

- `search_jira_tickets` - Search tickets with filters (type, status, assignee) and text search
- `get_jira_ticket` - Get full ticket details including linked issues, attachments, subtasks, and Epic children

**Returned fields for `get_jira_ticket`:**
- Basic: key, summary, description, status, issue_type, priority, assignee, reporter, labels, created, updated
- Relationships: linked_issues, parent (for subtasks), subtasks, epic_children (for Epics)
- Attachments: list of filenames

## Configuration

### AWS Authentication

Pass AWS credentials as CLI arguments (recommended to work around Claude Code env var bug):```bash
# Using Claude Code CLI
claude mcp add --scope user --transport stdio debug-mcp \
    -- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
    --aws-region us-west-2 \
    --aws-profile your-profile-name

Or in .mcp.json:```json
"args": [
"--from", "git+https://github.com/Coykto/debug_mcp",
"debug-mcp",
"--aws-region", "us-west-2",
"--aws-profile", "your-profile-name"
]


**Alternative**: Set environment variables before launching Claude Code:```bash
export AWS_REGION=us-west-2
export AWS_PROFILE=your-profile-name
# Then launch Claude Code

Jira Configuration

Jira integration allows you to search tickets and get full ticket details directly from Claude Code.

Step 1: Create a Jira API Token

  1. Go to Atlassian API Token Management
  2. Click Create API token
  3. Give it a descriptive label (e.g., "Debug MCP")
  4. Copy the generated token (you won't see it again)

Step 2: Gather Your Jira Details

You'll need:
- Host: Your Jira Cloud hostname (e.g., yourcompany.atlassian.net)
- Email: The email address associated with your Atlassian account
- Project: The project key for your default project (e.g., PROJ, DEV, CORE)
- Token: The API token from Step 1

Step 3: Configure Debug MCP

Option A: Claude Code CLI (Recommended)```bash
claude mcp add --scope user --transport stdio debug-mcp \
-- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
--aws-region us-west-2 \
--aws-profile your-profile-name \
--jira-host yourcompany.atlassian.net \
--jira-email your.email@company.com \
--jira-project PROJ \
--jira-token your-api-token


**Option B: Manual `.mcp.json` Configuration**```json
{
  "mcpServers": {
    "debug-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/Coykto/debug_mcp",
        "debug-mcp",
        "--aws-region", "us-west-2",
        "--aws-profile", "your-profile-name",
        "--jira-host", "yourcompany.atlassian.net",
        "--jira-email", "your.email@company.com",
        "--jira-project", "PROJ",
        "--jira-token", "your-api-token"
      ]
    }
  }
}

Option C: Use Environment Variable for Token

If you prefer not to store the token in your config, set JIRA_API_TOKEN as an environment variable before launching Claude Code:```bash
export JIRA_API_TOKEN=your-api-token


Then omit `--jira-token` from the CLI args (other Jira args are still required).

#### Configuration Reference

| Source | Name | Required | Description |
|--------|------|----------|-------------|
| CLI arg | `--jira-host` | Yes | Jira Cloud hostname (e.g., `company.atlassian.net`) |
| CLI arg | `--jira-email` | Yes | Atlassian account email |
| CLI arg | `--jira-project` | Yes | Default Jira project key (e.g., `PROJ`) |
| CLI arg | `--jira-token` | Yes* | Jira API token |
| Env var | `JIRA_API_TOKEN` | Yes* | Alternative to `--jira-token` CLI arg |

*Either `--jira-token` or `JIRA_API_TOKEN` is required.

#### Jira Troubleshooting

**"Jira credentials not configured" error:**
- Verify all required args are provided: `--jira-host`, `--jira-email`, `--jira-project`, and token
- Check that your API token is valid at Atlassian API Tokens

**"401 Unauthorized" error:**
- Your API token may have expired - create a new one
- Verify the email matches your Atlassian account exactly

**"Project not found" error:**
- Check the project key (not name) - it's the prefix in ticket IDs (e.g., `PROJ` in `PROJ-123`)
- Ensure your account has access to the project

## Troubleshooting

### Server won't start
- Check AWS credentials: `aws sts get-caller-identity --profile YOUR_PROFILE`
- Verify uvx is installed: `uvx --version`
- Check Claude Code MCP logs in settings

### Wrong AWS region/account
- Update `--aws-region` and `--aws-profile` CLI arguments
- Make sure the profile exists in `~/.aws/credentials`
- Verify the region is correct: `aws configure get region --profile YOUR_PROFILE`

### Environment variables not working
Due to a known bug in Claude Code, environment variables in the MCP `env` block aren't reliably passed to servers. **Use CLI arguments instead** (see installation examples above).

## Development

### Local Development```bash
# Install dependencies
uv sync

# Run the server locally
uv run debug-mcp --aws-region us-west-2 --aws-profile your-profile

# Test
uv run pytest

Architecture

The server uses a Tool Discovery Gateway pattern with direct boto3/SDK implementations:

Gateway Layer (src/debug_mcp/server.py):
- Single debug() tool exposed to Claude
- Handles discovery (tool="list", tool="list:cloudwatch")
- Routes execution to registered tools
- Validates arguments with Pydantic models

Registry System (src/debug_mcp/registry.py):
- Central registry for all tools with schemas
- Category-based organization
- @debug_tool() decorator for registration
- Validation and execution routing

Tool Implementations:
- CloudWatch (cloudwatch_logs.py + cloudwatch_registry.py): boto3 CloudWatch Logs client
- Step Functions (stepfunctions.py + stepfunctions_registry.py): boto3 Step Functions client
- LangSmith (langsmith.py + langsmith_registry.py): LangSmith SDK with multi-environment support
- Jira (jira.py + jira_registry.py): Jira SDK with lazy client initialization

Each *_registry.py file registers tools using the @debug_tool() decorator with schemas and handlers.

Team Sharing

Share with your team:
1. They update --aws-profile with their own profile name
2. Optionally adjust --aws-region if different
3. All 17 debugging tools are available through the single debug() gateway - no tool filtering needed

Contributing

Contributions are welcome! Some areas where PRs would be appreciated:

  • LangSmith CLI token support: Currently LangSmith credentials are loaded from AWS Secrets Manager (for prod/dev) or .env files (for local). Adding --langsmith-api-key CLI argument support (similar to Jira) would make setup easier for teams not using Secrets Manager.
  • Additional debugging tools: New tools for other AWS services (ECS, Lambda logs, X-Ray traces)
  • Bug fixes and improvements: Error handling, documentation, tests

To contribute:
1. Fork the repository
2. Create a feature branch
3. Make your changes (see Adding New Tools in CLAUDE.md)
4. Submit a PR

License

MIT License - See LICENSE file

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
debug MCP 怎么安装?

在客户端按下面的安装命令接入:uv run debug-mcp --aws-region us-west-2 --aws-profile your-profile。装完在客户端配置里引用同一个包或端点。

debug MCP 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

debug MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

debug MCP 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

debug MCP 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

debug MCP 能提供哪些能力?

资料显示能力标签包括 分布式系统、调试工具、Python、Claude。具体工具清单以官方文档为准。

debug MCP 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

debug MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。