@circleci/mcp-server-circleci
MCPA Model Context Protocol (MCP) server implementation for CircleCI, enabling natural language interactions with CircleCI functionality through MCP-enabled clients
Dimension scores
Compatibility
| Framework | Status | Notes |
|---|---|---|
| Claude Code | ✓ | — |
| OpenAI Agents SDK | ✓ | SSE transport preferred but stdio also works - may need minor configuration |
| LangChain | ✓ | Tool handlers are async and return text content - should wrap cleanly as LangChain StructuredTools, Response format with content array needs mapping to LangChain output |
Security findings
CIRCLECI_TOKEN exposed in environment without validation
src/clients/client.ts retrieves process.env.CIRCLECI_TOKEN and only checks if it exists, not if it's a valid token format. This token is then used throughout the application for API calls. If compromised or logged, it grants full CircleCI API access.
No input sanitization on project slugs and URLs
Functions like getProjectSlugFromURL and getPipelineNumberFromURL parse user-provided URLs using regex without validating the extracted values. A malicious URL could inject unexpected characters into API calls or cause regex denial-of-service (ReDoS).
Debug mode logs sensitive request/response data
Error messages may expose internal structure
No rate limiting on HTTP endpoints
Unbounded input from URL parameters
Reliability
Success rate
82%
Calls made
100
Avg latency
850ms
P95 latency
2500ms
Failure modes
- • Missing CIRCLECI_TOKEN environment variable causes immediate client initialization failure
- • Network timeouts on CircleCI API calls have no explicit timeout handling in HTTP client
- • URL parsing functions throw errors for malformed URLs rather than returning structured errors
- • Tool handlers may throw unhandled exceptions that propagate to MCP server without structured error response
- • Text truncation at 50KB may split JSON/structured data mid-object, breaking parseability
- • SSE transport errors during debug logging could cause crashes if JSON.stringify fails on circular references
- • No rate limiting protection against CircleCI API rate limits
- • Concurrent requests to stateless HTTP transport may face race conditions during tool registration
- • Error responses inconsistently use mcpErrorOutput vs throwing exceptions across different tools
Code health
License
Apache-2.0
Has tests
Yes
Has CI
Yes
Dependencies
42
Excellent code health. Active maintenance with daily commits, comprehensive test coverage across multiple modules (httpClient, mcpErrorOutput, outputTextTruncated, mcpResponse, getWorkflowIdFromURL, project-detection), TypeScript with proper typing, well-documented with extensive README (37KB), maintained CHANGELOG, CircleCI config for CI/CD, ESLint and Prettier configured, uses pnpm with lockfile. Published to npm registry. Has renovate.json for automated dependency updates. Strong contributor activity (8 active contributors). Minor areas: 12 open issues and 3 open PRs suggest active development but could be triaged faster. Overall, this is a professionally maintained, production-ready MCP server implementation.