# MCP Toolkit

[![PyPI version](https://badge.fury.io/py/mcp-toolkit.svg)](https://badge.fury.io/py/mcp-toolkit)
[![Python Versions](https://img.shields.io/pypi/pyversions/mcp-toolkit.svg)](https://pypi.org/project/mcp-toolkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/exycfs/mcp-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/exycfs/mcp-toolkit/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/exycfs/mcp-toolkit/branch/main/graph/badge.svg)](https://codecov.io/gh/exycfs/mcp-toolkit)
[![Downloads](https://pepy.tech/badge/mcp-toolkit/month)](https://pepy.tech/project/mcp-toolkit)

A comprehensive collection of production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers for common tools and services.

## Features

- **PostgreSQL Server** - Query, insert, update, and manage PostgreSQL databases
- **SQLite Server** - Lightweight SQLite database operations with full SQL support
- **Redis Server** - Key-value operations, pub/sub, and data structure manipulation
- **File System Server** - Secure file operations with sandboxing and access controls
- **GitHub API Server** - Repository management, issues, PRs, and more via GitHub API

## Installation

```bash
# Install from PyPI
pip install mcp-toolkit

# Or install specific servers only
pip install mcp-toolkit[postgres]
pip install mcp-toolkit[sqlite]
pip install mcp-toolkit[redis]
pip install mcp-toolkit[filesystem]
pip install mcp-toolkit[github]

# Install all servers
pip install mcp-toolkit[all]
```

## Quick Start

### PostgreSQL

```python
from mcp_toolkit.servers.postgres import PostgreSQLServer

server = PostgreSQLServer(
    connection_string="postgresql://user:pass@localhost:5432/mydb"
)
server.run()
```

### SQLite

```python
from mcp_toolkit.servers.sqlite import SQLiteServer

server = SQLiteServer(database_path="./data.db")
server.run()
```

### Redis

```python
from mcp_toolkit.servers.redis import RedisServer

server = RedisServer(redis_url="redis://localhost:6379/0")
server.run()
```

### File System

```python
from mcp_toolkit.servers.filesystem import FilesystemServer

server = FilesystemServer(
    root_dir="/path/to/workspace",
    read_only=False
)
server.run()
```

### GitHub API

```python
from mcp_toolkit.servers.github import GitHubServer

server = GitHubServer(
    github_token="ghp_..."
)
server.run()
```

## CLI Usage

```bash
# Run PostgreSQL server
mcp-toolkit postgres --connection-string "postgresql://localhost/mydb"

# Run SQLite server
mcp-toolkit sqlite --database ./data.db

# Run Redis server
mcp-toolkit redis --url redis://localhost:6379

# Run Filesystem server
mcp-toolkit filesystem --root ./workspace

# Run GitHub server
mcp-toolkit github --token $GITHUB_TOKEN
```

## Configuration

### Environment Variables

```bash
# PostgreSQL
POSTGRES_CONNECTION_STRING=postgresql://user:pass@localhost/db

# Redis
REDIS_URL=redis://localhost:6379/0

# GitHub
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
```

### Claude Desktop Configuration

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "postgres": {
      "command": "mcp-toolkit",
      "args": ["postgres", "--connection-string", "postgresql://localhost/mydb"]
    },
    "redis": {
      "command": "mcp-toolkit",
      "args": ["redis", "--url", "redis://localhost:6379"]
    }
  }
}
```

## API Reference

### PostgreSQL Server

| Tool | Description |
|------|-------------|
| `query` | Execute a SELECT query |
| `execute` | Execute an INSERT/UPDATE/DELETE statement |
| `list_tables` | List all tables in the database |
| `describe_table` | Get table schema information |
| `explain_query` | Get query execution plan |

### SQLite Server

| Tool | Description |
|------|-------------|
| `query` | Execute a SELECT query |
| `execute` | Execute an INSERT/UPDATE/DELETE statement |
| `list_tables` | List all tables |
| `describe_table` | Get table schema |
| `vacuum` | Optimize database storage |

### Redis Server

| Tool | Description |
|------|-------------|
| `get` | Get a key's value |
| `set` | Set a key-value pair |
| `delete` | Delete one or more keys |
| `keys` | List keys matching a pattern |
| `hget` | Get a hash field value |
| `hset` | Set a hash field |
| `lrange` | Get a list range |
| `publish` | Publish a message to a channel |

### Filesystem Server

| Tool | Description |
|------|-------------|
| `read_file` | Read file contents |
| `write_file` | Write content to a file |
| `list_directory` | List directory contents |
| `create_directory` | Create a new directory |
| `delete_file` | Delete a file |
| `move_file` | Move/rename a file |
| `search_files` | Search for files by pattern |

### GitHub Server

| Tool | Description |
|------|-------------|
| `list_repos` | List user repositories |
| `get_repo` | Get repository details |
| `list_issues` | List repository issues |
| `create_issue` | Create a new issue |
| `list_prs` | List pull requests |
| `get_file` | Get file contents from repo |
| `search_code` | Search code across repos |

## Development

```bash
# Clone the repository
git clone https://github.com/exycfs/mcp-toolkit.git
cd mcp-toolkit

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linters
ruff check .
mypy src/

# Format code
ruff format .
```

## Contributing

Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built on the [Model Context Protocol](https://modelcontextprotocol.io/) specification
- Inspired by the MCP ecosystem and community

## Support

- [GitHub Issues](https://github.com/exycfs/mcp-toolkit/issues)
- [Discussions](https://github.com/exycfs/mcp-toolkit/discussions)