# @kadreio/mcp-coding-agents
[](https://github.com/kadreio/mcp-coding-agents/actions/workflows/ci.yml)
[](https://github.com/kadreio/mcp-coding-agents/actions/workflows/release.yml)
[](https://www.npmjs.com/package/@kadreio/mcp-coding-agents)
A transport-agnostic MCP (Model Context Protocol) server with Claude Code, Gemini, and Codex agent integrations. Supports both STDIO and HTTP transports for flexible AI model context management.
## Features
- 🚀 **Transport-agnostic architecture** - Clean separation between business logic and transport layers
- 🔄 **Multiple transport modes** - STDIO for direct process communication, HTTP with SSE for network access
- 🤖 **Multiple AI agents** - Claude Code, Gemini, and Codex integrations
- 📦 **Built-in tools** - BMI calculator, timestamp generator, command execution, and more
- 🔧 **Extensible design** - Easy to add new tools, prompts, and transports
- 💬 **Real-time streaming** - Support for notifications and SSE in HTTP mode
## Installation
```bash
npm install -g @kadreio/mcp-coding-agents
```
### Native Dependencies
This package uses `better-sqlite3` for session persistence, which requires compilation of native code. On most systems, prebuilt binaries are available and installation is automatic. If you encounter issues:
**macOS/Linux**: Ensure you have build tools installed:
```bash
# macOS
xcode-select --install
# Ubuntu/Debian
sudo apt-get install build-essential
# RHEL/CentOS
sudo yum groupinstall "Development Tools"
```
**Windows**: Install windows-build-tools:
```bash
npm install --global windows-build-tools
```
## Quick Start
### Using npx (no installation required)
```bash
# Default mode (HTTP on port 3050)
npx @kadreio/mcp-claude-code
# STDIO mode for direct process communication
npx @kadreio/mcp-claude-code stdio
# HTTP mode with custom port
npx @kadreio/mcp-claude-code http --port 3051
# With specific host binding
npx @kadreio/mcp-claude-code http --host 0.0.0.0
```
### After global installation
```bash
# Default HTTP mode
mcp-claude-code
# STDIO mode
mcp-claude-code stdio
# HTTP mode with options
mcp-claude-code http --port 3051 --no-cors
```
## Transport Modes
### STDIO Mode
Best for editor integrations and direct process communication:
```bash
mcp-claude-code stdio
```
- Communicates via stdin/stdout using JSON-RPC
- No network overhead
- Ideal for local development tools
### HTTP Mode
Best for network access and web integrations:
```bash
mcp-claude-code http --port 3050
```
- RESTful API with SSE support for streaming
- Session management for stateful interactions
- CORS support (configurable)
- Health check endpoint at `/health`
## Available Tools
### Core Tools
- `calculate_bmi` - Calculate Body Mass Index
- `get_timestamp` - Get current timestamp
- `execute_command` - Execute shell commands with timeout support
- `stream_sse_timestamps` - Generate streaming timestamps (HTTP mode)
### AI Agent Tools
- `claude_code_query` - Query Claude Code with streaming responses
- `gemini_query` - Execute Gemini CLI commands
- `codex_query` - Execute Codex with JSONL streaming
## Environment Variables
```bash
# Core Configuration
PORT=3050 # HTTP server port (default: 3050)
# Claude Code Configuration
ANTHROPIC_API_KEY=sk-ant-... # Required for Claude Code
CLAUDE_CODE_ENABLE=true # Enable/disable Claude Code tool
CLAUDE_CODE_DEFAULT_CWD=/path # Default working directory
CLAUDE_CODE_DEFAULT_MODEL=... # Default Claude model
CLAUDE_CODE_MAX_MESSAGES=100 # Max messages to return
CLAUDE_CODE_EXECUTABLE_PATH=/path/to/claude # Path to Claude executable (auto-detected if not set)
# Agent Configuration
GEMINI_API_KEY=... # For Gemini agent
OPENAI_API_KEY=... # For Codex agent
# Session Storage (HTTP mode)
MCP_DATABASE_PATH=/path/to/sessions.db # Custom database location
# Default: ~/.local/share/mcp-coding-agents/sessions.db (Linux/macOS)
# %LOCALAPPDATA%\mcp-coding-agents\sessions.db (Windows)
```
## Development
```bash
# Clone the repository
git clone https://github.com/kadreio/mcp-claude-code.git
cd mcp-claude-code
# Install dependencies
npm install
# Build the project
npm run build
# Development mode with hot reload
npm run mcp:dev # Default HTTP mode
npm run mcp:stdio:dev # STDIO mode
npm run mcp:http:dev # Explicit HTTP mode
# Run tests
npm test
npm run test:coverage
```
## Architecture
The server uses a clean, transport-agnostic architecture:
```
CoreMCPServer (Business Logic)
↓
Transport Interface
↙ ↘
STDIO HTTP
Transport Transport
```
- **CoreMCPServer**: Contains all business logic, tool handlers, and agent integrations
- **Transport Layer**: Thin adapters for different communication protocols
- **Unified CLI**: Single entry point with transport selection
## API Endpoints (HTTP Mode)
- `POST /mcp` - Main MCP endpoint for JSON-RPC requests
- `GET /mcp` - SSE endpoint for streaming notifications
- `GET /health` - Health check endpoint
- `GET /` - Server information and capabilities
## HTTPS Support
The server supports HTTPS for secure communication:
### Quick Start (Auto-Generated Certificate)
```bash
# Run with HTTPS - automatically generates a self-signed certificate
npx @kadreio/mcp-coding-agents http --https
```
This will automatically generate a self-signed certificate on the fly. Perfect for development!
### Using Your Own Certificates
```bash
# Generate self-signed certificates
./generate-certs.sh
# Run with HTTPS using generated certificates
npx @kadreio/mcp-coding-agents http --https --cert ./certs/server.cert --key ./certs/server.key
```
### Using Custom Certificates
```bash
# Run with your own certificates
npx @kadreio/mcp-coding-agents http --https \
--cert /path/to/certificate.pem \
--key /path/to/private-key.pem \
--ca /path/to/ca-certificate.pem # Optional CA certificate
```
### HTTPS Options
- `--https` - Enable HTTPS mode
- `--cert <path>` - Path to SSL certificate file
- `--key <path>` - Path to SSL private key file
- `--ca <path>` - Path to SSL CA certificate file (optional)
## MCP Client Configuration
### For STDIO mode
```json
{
"mcpServers": {
"claude-code": {
"command": "npx",
"args": ["@kadreio/mcp-claude-code", "stdio"],
"env": {
"ANTHROPIC_API_KEY": "your-api-key"
}
}
}
}
```
### For HTTP mode
```json
{
"mcpServers": {
"claude-code": {
"url": "http://localhost:3050/mcp",
"transport": "http"
}
}
}
```
## Contributing
See [CLAUDE.md](./CLAUDE.md) for development guidelines and architecture details.
## License
MIT
## Contributing
Contributions are welcome\! Please feel free to submit a Pull Request.
### Development Setup
```bash
git clone https://github.com/kadreio/mcp-coding-agents.git
cd mcp-coding-agents
npm install
npm test
```
### Releasing
Releases are automated via GitHub Actions when you push a version tag:
```bash
npm run release:patch # 1.0.0 → 1.0.1
npm run release:minor # 1.0.0 → 1.1.0
npm run release:major # 1.0.0 → 2.0.0
npm run release:beta # 1.0.0 → 1.0.1-beta.0
```
See [RELEASING.md](./RELEASING.md) for detailed release instructions.
