README.md•6.25 kB
# MCP Pickaxe Server
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
An MCP (Model Context Protocol) server that connects AI assistants like Claude to the [Pickaxe](https://pickaxe.co) platform. Manage your AI agents, knowledge bases, users, and analytics directly through natural language.
## Why Use This?
If you're building AI agents on Pickaxe, this MCP server lets you:
- **Analyze agent conversations** - Review chat history to identify knowledge gaps and improve agent performance
- **Manage knowledge bases** - Create, update, and connect documents to your agents without leaving your AI workflow
- **Handle user management** - Create users, manage access, send invitations, and track usage
- **Work across multiple studios** - Seamlessly switch between different Pickaxe studios in a single session
- **Automate workflows** - Let Claude handle repetitive Pickaxe admin tasks
## Features
| Category | Tools |
|----------|-------|
| **Studios** | List configured studios, switch between them |
| **Chat History** | Fetch and analyze agent conversation logs |
| **Documents** | Create, list, get, delete, connect/disconnect to agents |
| **Users** | Create, list, get, update, delete, invite |
| **Products** | List available products and bundles |
| **Memory** | List memory schemas, retrieve user memories |
## Prerequisites
- Node.js 18+
- A [Pickaxe](https://pickaxe.co) account with API access
- Your Pickaxe Studio API key(s)
## Installation
### Option 1: Clone and Build
```bash
git clone https://github.com/YOUR_USERNAME/mcp-pickaxe.git
cd mcp-pickaxe
npm install
npm run build
```
### Option 2: Install from npm (coming soon)
```bash
npm install -g mcp-pickaxe
```
## Configuration
### 1. Get Your Pickaxe API Key
1. Log in to [Pickaxe Studio](https://studio.pickaxe.co)
2. Navigate to Settings > API
3. Copy your Studio API key (starts with `studio-`)
### 2. Configure Your MCP Client
#### For Claude Desktop
Add to your Claude Desktop config file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"pickaxe": {
"command": "node",
"args": ["/path/to/mcp-pickaxe/dist/index.js"],
"env": {
"PICKAXE_STUDIO_MAIN": "studio-your-api-key-here"
}
}
}
}
```
#### For Claude Code
Add to `~/.claude.json`:
```json
{
"mcpServers": {
"pickaxe": {
"command": "node",
"args": ["/path/to/mcp-pickaxe/dist/index.js"],
"env": {
"PICKAXE_STUDIO_MAIN": "studio-your-api-key-here"
}
}
}
}
```
### Multi-Studio Configuration
To work with multiple Pickaxe studios, add multiple environment variables:
```json
{
"env": {
"PICKAXE_STUDIO_PRODUCTION": "studio-xxx-xxx-xxx",
"PICKAXE_STUDIO_STAGING": "studio-yyy-yyy-yyy",
"PICKAXE_STUDIO_DEV": "studio-zzz-zzz-zzz",
"PICKAXE_DEFAULT_STUDIO": "PRODUCTION"
}
}
```
Then specify which studio to use in your requests:
- If you set `PICKAXE_DEFAULT_STUDIO`, that studio is used when none is specified
- If only one studio is configured, it's used automatically
- Otherwise, pass `studio="STAGING"` (or similar) to any tool
## Usage Examples
Once configured, you can interact with Pickaxe through natural language:
### Analyze Agent Performance
> "Show me the last 20 conversations from my support agent"
> "What questions are users asking that my agent can't answer?"
### Manage Knowledge Base
> "Create a new document called 'FAQ' with this content: [your content]"
> "Connect the FAQ document to my customer support agent"
> "List all documents in my knowledge base"
### User Management
> "Show me all users and their usage stats"
> "Create a new user with email user@example.com and give them access to the Pro product"
> "Send invitations to these emails: [list of emails]"
### Multi-Studio Operations
> "List all users in my staging studio"
> "Compare the documents between production and staging"
## Available Tools
### Studio Management
- `studios_list` - List all configured studios and the current default
### Chat History
- `chat_history` - Fetch conversation history for an agent
- Parameters: `pickaxeId`, `skip`, `limit`, `format` ("messages" or "raw"), `studio`
### Document Management
- `doc_create` - Create document from content or URL
- `doc_list` - List all documents (with pagination)
- `doc_get` - Get a specific document
- `doc_delete` - Delete a document
- `doc_connect` - Link document to an agent
- `doc_disconnect` - Unlink document from an agent
### User Management
- `user_list` - List all users with access and usage info
- `user_get` - Get a specific user by email
- `user_create` - Create a new user
- `user_update` - Update user details, products, or usage
- `user_delete` - Delete a user
- `user_invite` - Send email invitations
### Products
- `products_list` - List available products/bundles
### Memory
- `memory_list` - List memory schemas
- `memory_get_user` - Get collected memories for a user
## Development
```bash
# Run in development mode (auto-reloads)
npm run dev
# Build for production
npm run build
# Run the built version
npm start
```
## Troubleshooting
### "No Pickaxe studios configured"
Ensure you have at least one `PICKAXE_STUDIO_*` environment variable set in your MCP config.
### "Studio not found"
Check that the studio name matches exactly (case-insensitive). Run `studios_list` to see available options.
### "Pickaxe API error (401)"
Your API key is invalid or expired. Get a new one from Pickaxe Studio settings.
### "Pickaxe API error (403)"
Your API key doesn't have permission for this operation. Check your Pickaxe account permissions.
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
MIT License - see [LICENSE](LICENSE) for details.
## Links
- [Pickaxe Platform](https://pickaxe.co)
- [Pickaxe Studio](https://studio.pickaxe.co)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Specification](https://spec.modelcontextprotocol.io)