Content
# AnyMCP
**Turn any folder into an MCP service.**
Drop files into `resources/`, scripts into `tools/`, and AnyMCP exposes them to any MCP-speaking agent — with authentication, schema generation, and observability handled for you.
Self-hosted. Multi-service. Any language.
[](LICENSE)
---
## What it does
- **Convention over configuration.** Drop files and scripts into a directory. AnyMCP discovers them, detects MIME types, and auto-generates JSON schemas via LLM — no hand-authored definitions.
- **Multi-service isolation.** Host many services on one instance, each with its own auth tokens, resources, and tools.
- **Any runtime.** Write tools in Python, Node.js, Bash, TypeScript, Ruby, or compiled binaries. If it reads stdin and writes stdout, it works.
- **Security built in.** Per-service bearer tokens — create, rotate, revoke. SHA-256 hashed at rest.
- **Observability built in.** Real-time activity logs, per-service health metrics, CSV export for audit trails.
- **Web dashboard.** Create services, manage tokens, toggle resources and tools, test everything in the built-in playground.
---
## Quick start
```bash
git clone https://github.com/palarix/any-mcp.git
cd any-mcp
bun install
bun run dev
```
AnyMCP finds an available port, opens in your browser, and you're managing services in under a minute.
### Create a service
```bash
mkdir my-service && cd my-service
# Add a resource
mkdir resources
echo '{"primary": "#5e6ad2", "text": "#e4e4e7"}' > resources/colors.json
# Add a tool
mkdir tools
cat > tools/greet.py << 'EOF'
#!/usr/bin/env python3
import sys, json
args = json.loads(sys.stdin.read())
print(f"Hello, {args.get('name', 'World')}!")
EOF
chmod +x tools/greet.py
```
That's it. AnyMCP picks it up, generates schemas, and serves it over MCP.
---
## Installation
### From source (recommended)
```bash
git clone https://github.com/palarix/any-mcp.git
cd any-mcp
bun install
# Development mode (hot reload)
bun run dev
# Production build
bun run build
bun run start
```
### Docker
```bash
docker build -t any-mcp .
docker run --rm -p 4000:3000 -v ./services:/app/services any-mcp
```
---
## CLI
```
any-mcp [command] [options]
```
| Command | Description |
|---|---|
| `start` (default) | Start the AnyMCP server |
| `init` | Scaffold `.any-mcp/` in the current directory |
| `add-service <name>` | Create a new service directory |
| `services` | List registered services |
| Option | Description |
|---|---|
| `--port <n>` | Override port (default: auto from 4000) |
| `--dir <path>` | Target directory (default: `.`) |
| `--server` | Headless mode — no browser |
| `--global` | Force global mode (`~/.config/any-mcp/`) |
| `--quiet` | Suppress non-error output |
| `--verbose` | Detailed logs |
---
## How services work
A service is a directory with an `mcp-service.json` descriptor:
```
my-service/
├── mcp-service.json
├── resources/
│ ├── brand-guide.md
│ ├── colors.json
│ └── logo.svg
└── tools/
├── check-contrast.py
└── generate-palette.js
```
```json
{
"name": "my-service",
"displayName": "My Service",
"description": "Design system context for agents",
"enabled": true,
"resources": {
"enabled": true,
"paths": ["./resources"]
},
"tools": {
"enabled": true,
"paths": ["./tools"]
},
"auth": {
"enabled": true,
"type": "bearer"
}
}
```
### Resources
Any file in a `resources/` directory becomes an MCP resource. AnyMCP detects the MIME type and serves the content. Agents read resources for context — design tokens, documentation, config files, data.
### Tools
Scripts in a `tools/` directory become MCP tools. The contract is simple:
| Direction | Channel | Format |
|---|---|---|
| **Input** | stdin | JSON object |
| **Output** | stdout | Any text (returned to agent) |
| **Logs** | stderr | Captured, not returned |
| **Status** | exit code | 0 = success, non-zero = error |
Write tools in whatever language fits the job:
**Python**
```python
#!/usr/bin/env python3
import sys, json
args = json.loads(sys.stdin.read())
name = args.get("name", "World")
print(f"Hello, {name}!")
```
**JavaScript**
```javascript
#!/usr/bin/env node
const fs = require("fs");
const args = JSON.parse(fs.readFileSync(0, "utf-8"));
console.log(`Hello, ${args.name || "World"}!`);
```
**Bash**
```bash
#!/bin/bash
input=$(cat)
name=$(echo "$input" | jq -r '.name // "World"')
echo "Hello, $name!"
```
Compiled binaries work too — any executable that reads stdin and writes stdout.
### Schema generation
AnyMCP auto-generates input schemas for tools using an LLM. You can also define schemas manually in `mcp-service.json` or edit them through the dashboard.
---
## Connecting agents
AnyMCP serves each service at `/mcp/<service-name>` using [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
### Claude Code
```json
{
"mcpServers": {
"my-service": {
"type": "url",
"url": "http://localhost:4000/mcp/my-service",
"headers": {
"Authorization": "Bearer <TOKEN>"
}
}
}
}
```
### Cursor / VS Code
```json
{
"mcp": {
"servers": {
"my-service": {
"type": "url",
"url": "http://localhost:4000/mcp/my-service",
"headers": {
"Authorization": "Bearer <TOKEN>"
}
}
}
}
}
```
Generate tokens from the dashboard under each service's authentication settings.
---
## Data storage
AnyMCP uses a local-first strategy:
| Mode | Config | Services | When |
|---|---|---|---|
| **Local** | `./.any-mcp/config.json` | Current directory | After `any-mcp init` |
| **Global** | `~/.config/any-mcp/config.json` | `~/.config/any-mcp/services/` | Default fallback |
Use `--global` to force global mode when a local config exists.
---
## Use cases
**Brand design system** — Serve your design tokens, typography rules, and component guidelines as resources. Add a contrast-checker tool. Your coding agent generates on-brand UI without hallucinating colors.
**DevOps runbooks** — Expose monitoring scripts as tools and config files as resources. An ops agent can check service status, query metrics, and follow your runbook — with auth scoping what it can reach.
**Knowledge base** — Drop markdown docs, API specs, or data files into resources. Any agent with access gets grounded context instead of guessing.
**Internal APIs** — Wrap internal endpoints as tool scripts. Agents call them through MCP with proper auth, without needing direct network access.
---
## Configuration
Config priority: CLI flags > environment variables > config file > defaults.
```json
{
"server": {
"port": 4000,
"host": "localhost"
},
"llm": {
"provider": "openai",
"apiKey": "sk-...",
"model": "gpt-4",
"baseUrl": "https://api.openai.com/v1"
},
"security": {
"tokenExpiry": "never",
"allowedOrigins": ["*"]
},
"logging": {
"level": "info",
"retentionDays": 30
}
}
```
The LLM settings power auto-generation of tool schemas. Any OpenAI-compatible endpoint works.
See `.env.example` for environment variable options.
---
## Health check
```bash
curl http://localhost:4000/api/health
```
```json
{
"status": "healthy",
"uptime": 123.45,
"services": { "total": 5, "active": 4 },
"timestamp": "2026-01-22T12:34:56.789Z"
}
```
---
## Contributing
```bash
git clone https://github.com/palarix/any-mcp.git
cd any-mcp
bun install
bun run dev
```
The dev server runs at `http://localhost:4000` with the example services in `examples/`.
### Issue tracking
This project uses [Exponential (xpo)](https://github.com/palarix/exponential) for issue tracking. Issues live in `.xpo/` alongside the code.
```bash
xpo list # View all issues
xpo add "title" # Create an issue
xpo board # Open the web board
```
---
## License
[MIT](LICENSE)
