Contributing to MCP ↗

node --version  # Should be 24.x or higher
npm --version   # Should be 11.x or higher
git --version   # Any recent version

    git clone https://github.com/YOUR-USERNAME/modelcontextprotocol.git
    cd modelcontextprotocol
    ```

Replace `YOUR-USERNAME` with your GitHub username.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Install dependencies"></span>
```bash
    npm install
    ```

This installs the tools needed for schema generation, documentation building, and validation.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Verify everything works"></span>
```bash
    npm run check
    ```

This runs TypeScript compilation, schema validation, example validation, documentation link checks, and formatting checks. If everything passes, your environment is good and you're ready to contribute.
  <span class="step-end"></span>
<span class="steps-end"></span>

If `npm run check` fails, see [Troubleshooting](#troubleshooting) below.

### Step 2: Find Something to Work On

While a lot of the items you might see tracked in the repository can feel intimidating, especially
for newcomers, there are plenty of places where you can start with your first improvements:

1. **Documentation improvements** - Help us fix typos, unclear explanations, broken links, or
   incomplete examples
2. **Issues labeled `good first issue`** - Tackle issues tagged in the
   [specification repo](https://github.com/modelcontextprotocol/modelcontextprotocol/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
   as well as our SDK repos
3. **Schema examples** - Add examples to `schema/draft/examples/` to make it easier for developers
   to understand protocol primitives

### Step 3: Make Your Change

Create your changes in a dedicated branch.

<span class="steps-start"></span>
  <span class="step-marker" data-step-title="Create a branch"></span>
```bash
    git checkout -b fix/your-description
    ```

Use a descriptive branch name that reflects your change, like `fix/typo-in-tools-doc` or `feat/add-example-for-resources`.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Make your changes"></span>
Edit the relevant files in your local copy. If you're editing schema files, remember to run `npm run generate:schema` to regenerate the JSON schema and documentation.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Run checks"></span>
```bash
    npm run check
    ```

Fix any issues before committing. If you have formatting errors, `npm run format` can auto-fix most of them.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Commit with a clear message"></span>
```bash
    git commit -m "Fix typo in tools documentation"
    ```

Write a concise message that describes what you changed and why. Reference issue numbers if applicable (e.g., `Fix typo in tools documentation (#123)`).
  <span class="step-end"></span>
<span class="steps-end"></span>

### Step 4: Submit a Pull Request

When you're ready, push your branch and open a pull request.

<span class="steps-start"></span>
  <span class="step-marker" data-step-title="Push your branch"></span>
```bash
    git push origin fix/your-description
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Open a PR on GitHub"></span>
You can use the [GitHub CLI](https://cli.github.com/) to make this process easier:

```bash
    gh pr create --fill
    ```

Alternatively, navigate to your fork on GitHub and click **Compare & pull request**.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Fill in the PR template"></span>
Provide a clear description of your changes and link any related issues.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Wait for review"></span>
Maintainers typically respond within 1-5 business days.
  <span class="step-end"></span>
<span class="steps-end"></span>

<span class="callout-start" data-callout-type="tip"></span>
  That's it, **congratulations on your first contribution**! Every improvement,
  no matter how small, helps make MCP better for everyone.
<span class="callout-end"></span>

### What Makes a Good Contribution

Help us review your contribution quickly by following these patterns:

| Harder to Review                             | Thoughtful and Impactful                         |
| -------------------------------------------- | ------------------------------------------------ |
| Large PR with unrelated changes              | Focused PR addressing one issue                  |
| Reformatting code without functional changes | Fixing a bug with a clear explanation            |
| Vague commit messages ("fixed stuff")        | Descriptive commits linking to issues            |
| Submitting with failing CI checks            | All CI tests pass before requesting review       |
| Duplicating existing documentation           | Documenting an undocumented feature or edge case |

## Types of Contributions

Different contributions follow different processes depending on their scope.

<span class="callout-start" data-callout-type="tip"></span>
  Not sure which category your change falls into? Ask in the [MCP Contributor
  Discord](/community/communication#discord) before starting any significant
  work.
<span class="callout-end"></span>

### Small Changes (Direct PR)

Simply submit a pull request directly to the repo for:

* Bug fixes and typo corrections
* Documentation improvements, such as bringing clarity to an ambiguous or unclear section
* Adding examples to existing features
* Minor schema fixes that don't materially change the specification or SDK behavior
* Test improvements

### Major Changes (SEP Required)

Anything that changes the MCP specification requires following the
[Specification Enhancement Proposal (SEP)](/community/sep-guidelines) process. This includes, but
is not limited to:

* New protocol features or API methods
* Breaking changes to existing behavior
* Changes to the message format or schema structure
* New interoperability standards
* Governance or process changes

Here are a few concrete examples of what would require following the SEP steps:

* Adding a new RPC method like `tools/execute`
* Changing how authentication and authorization works
* Adding a new capability negotiation field
* Modifying the transport layer specification

## Working with the Specification Repository

Once you've determined [what type of contribution](#types-of-contributions) you're making, here's
how to work with the specification repository.

### Schema Changes

The TypeScript schema (`schema/draft/schema.ts`) is the **source of truth** for the protocol. It
defines every message type, request/response structure, and primitive (tools, resources, prompts)
that clients and servers exchange. SDK implementers across all languages rely on this schema to
build conformant implementations.

When you run `npm run generate:schema`, it generates:

* The JSON schema (`schema/draft/schema.json`) for validation
* The Schema Reference documentation (`docs/specification/draft/schema.mdx`)

To modify the schema:

<span class="steps-start"></span>
  <span class="step-marker" data-step-title="Edit the TypeScript schema"></span>
Make your changes in `schema/draft/schema.ts`.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Add examples (optional)"></span>
Add JSON examples in `schema/draft/examples/[TypeName]/` (e.g., `Tool/my-example.json`). Reference them in the schema using `@example` + `@includeCode` JSDoc tags.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Generate JSON schema and docs"></span>
```bash
    npm run generate:schema
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Validate your changes"></span>
```bash
    npm run check
    ```
  <span class="step-end"></span>
<span class="steps-end"></span>

### Documentation Changes

Docs are written in [MDX format](https://mdxjs.com/) (Markdown with JSX components) and powered by
[Mintlify](https://mintlify.com/). The `docs/` directory contains:

* `docs/docs/` - Guides and tutorials for getting started and building with MCP
* `docs/specification/` - Formal protocol specification (versioned by date)

Here is how you can contribute to our documentation:

<span class="steps-start"></span>
  <span class="step-marker" data-step-title="Start the local docs server"></span>
```bash
    npm run serve:docs
    ```

This launches a live preview at `http://localhost:3000` with hot reloading.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Make your changes"></span>
Edit the relevant `.mdx` files. You can use [Mintlify components](https://www.mintlify.com/docs/components) like `<span class="callout-start" data-callout-type="note"></span>`, `<span class="callout-start" data-callout-type="tip"></span>`, `<span class="steps-start"></span>`, and `<Card>` for richer formatting.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Check for issues"></span>
```bash
    npm run check:docs
    ```

This validates formatting, broken links, and other common issues.
  <span class="step-end"></span>
<span class="steps-end"></span>

### Major Protocol Changes

For significant changes, follow the [SEP process](/community/sep-guidelines). Prior to spending a
lot of time on a spec proposal, make sure to follow these best practices.

<span class="steps-start"></span>
  <span class="step-marker" data-step-title="Validate your idea first"></span>
Discuss in an [Interest Group](/community/working-interest-groups) or on
[Discord](https://discord.gg/6CSzBmMkjX).
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Build a prototype"></span>
Demonstrate practical application of your idea.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Find a sponsor"></span>
A maintainer from the [maintainer
list](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md)
who will champion your proposal.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Write the SEP"></span>
Follow the [SEP Guidelines](/community/sep-guidelines).
  <span class="step-end"></span>
<span class="steps-end"></span>

## Working with the SDK Repositories

MCP maintains official SDKs in multiple languages. Contributions are welcome - whether you're
fixing bugs, improving performance, adding features, or enhancing documentation.

<span class="callout-start" data-callout-type="note"></span>
  Each SDK has its own repository, maintainers, and contribution guidelines.
  Some SDKs are maintained in collaboration with larger partner organizations,
  such as Google, Microsoft, JetBrains, and others, so processes may vary
  slightly between repositories.
<span class="callout-end"></span>

### Before Contributing to an SDK

Before diving into code, follow these steps.

<span class="steps-start"></span>
  <span class="step-marker" data-step-title="Open an issue first"></span>
Before starting significant work, open an issue to discuss your approach.
This helps avoid duplicate effort, ensures your contribution aligns with the
SDK's direction, and gives maintainers a chance to provide early feedback.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Join the SDK channel"></span>
Find the relevant channel in [Discord](https://discord.gg/6CSzBmMkjX) (e.g.,
`#typescript-sdk-dev`, `#python-sdk-dev`).
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Read the SDK's CONTRIBUTING.md"></span>
Each repository has its own `CONTRIBUTING.md` with specific instructions for
setting up your development environment, coding standards, commit message
conventions, and PR requirements.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Write tests"></span>
All contributions should include appropriate test coverage. Bug fixes should
include a test that reproduces the issue, and new features should have tests
covering the expected behavior. This helps maintain SDK reliability and
prevents regressions.
  <span class="step-end"></span>
<span class="steps-end"></span>

### SDK Repositories

<span class="card-group-start" data-cols="2"></span>
  <span class="card-start" data-card-title="TypeScript SDK" data-card-icon="square-js" data-card-href="https://github.com/modelcontextprotocol/typescript-sdk"></span>

  <span class="card-start" data-card-title="Python SDK" data-card-icon="python" data-card-href="https://github.com/modelcontextprotocol/python-sdk"></span>

  <span class="card-start" data-card-title="Go SDK" data-card-icon="golang" data-card-href="https://github.com/modelcontextprotocol/go-sdk"></span>

  <span class="card-start" data-card-title="Kotlin SDK" data-card-icon="square-k" data-card-href="https://github.com/modelcontextprotocol/kotlin-sdk"></span>

  <span class="card-start" data-card-title="Java SDK" data-card-icon="java" data-card-href="https://github.com/modelcontextprotocol/java-sdk"></span>

  <span class="card-start" data-card-title="C# SDK" data-card-icon="square-c" data-card-href="https://github.com/modelcontextprotocol/csharp-sdk"></span>

  <span class="card-start" data-card-title="Swift SDK" data-card-icon="swift" data-card-href="https://github.com/modelcontextprotocol/swift-sdk"></span>

  <span class="card-start" data-card-title="Rust SDK" data-card-icon="rust" data-card-href="https://github.com/modelcontextprotocol/rust-sdk"></span>

  <span class="card-start" data-card-title="Ruby SDK" data-card-icon="gem" data-card-href="https://github.com/modelcontextprotocol/ruby-sdk"></span>

  <span class="card-start" data-card-title="PHP SDK" data-card-icon="php" data-card-href="https://github.com/modelcontextprotocol/php-sdk"></span>
<span class="card-group-end"></span>

## Getting Help

### Communication Channels

Got questions or need guidance? The MCP community is here to help.

* **[Discord](/community/communication#discord)** - Real-time discussion with contributors and
  maintainers, focused on MCP contributions (not general MCP support)
* **[GitHub Discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions)**
  \- Exploration and conversation: **feature requests**, questions, roadmap planning, and proposals
  that need input before becoming concrete tasks
* **[GitHub Issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues)** -
  Actionable work: bug reports with reproducible steps, documentation fixes, and tasks that are
  well-defined and ready to implement (not feature requests)

This separation helps maintainers focus on work that's ready for implementation while giving ideas
room to develop. If you're unsure whether something is ready to be an issue, start with a
discussion. For a complete guide, see our [Contributor Communication](/community/communication)
documentation.

For protocol discussions, join [Working Group](/community/working-interest-groups) channels like
`#auth-wg` or `#server-identity-wg`. For SDK help, find your language's channel (e.g.,
`#typescript-sdk-dev`).

### Finding a Sponsor for SEPs

A **sponsor** is a Core Maintainer or Maintainer who champions your SEP through the review
process. They provide feedback, help refine your proposal, and present it at Core Maintainer
meetings.

<span class="callout-start" data-callout-type="warning"></span>
  Every SEP needs a sponsor to move forward. SEPs that don't find a sponsor
  within 6 months are marked as **dormant**. Dormant SEPs aren't rejected
  outright - they can be revived later if a sponsor is found or the proposal is
  re-assessed to be needed.
<span class="callout-end"></span>

To find a sponsor:

<span class="steps-start"></span>
  <span class="step-marker" data-step-title="Find relevant maintainers"></span>
Look at the [maintainer
list](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md)
to find maintainers working in your area.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Tag maintainers in your PR"></span>
Tag 1-2 relevant maintainers (don't spam everyone).
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Share in Discord"></span>
Post your PR in the relevant Discord channel to increase visibility.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Follow up if needed"></span>
If no response after 2 weeks, ask in `#general` or reach out to a Core
Maintainer.
  <span class="step-end"></span>
<span class="steps-end"></span>

Maintainers review open proposals regularly, but response time varies based on complexity and
availability.

## Troubleshooting

Sometimes things don't go as planned - that's completely normal! Here are solutions to common
issues. If you're still stuck, don't hesitate to ask for help in
[Discord](/community/communication#discord). The community is friendly and happy to help you get
unstuck.

### `npm run check` fails

Common causes:

* **Wrong Node.js version** - Ensure you have Node.js 24+
* **Missing dependencies** - Run `npm install` again
* **Schema out of sync** - Run `npm run generate:schema`
* **Formatting issues** - Run `npm run format` to auto-fix

### My PR has been sitting unnoticed for weeks

1. Ensure all CI checks pass
2. Politely ping the desired reviewer in a comment
3. Ask in the relevant Discord channel
4. For urgent issues, reach out to a Core Maintainer

### I can't find a sponsor for my SEP

1. Make sure your idea has been discussed in Discord or an Interest Group first
2. Proposals with demonstrated community interest are more likely to find sponsors
3. Consider whether your change might be too large - could it be split into smaller SEPs?

### My SEP was rejected

Don't take it personally - a SEP rejection doesn't mean your idea was bad. SEPs can be rejected
for many reasons: timing, scope, competing priorities, or simply because the protocol isn't ready
for that change yet. The feedback you receive is valuable and often points toward a path forward.

Rejection is not permanent. You have a few options ahead:

1. **Address the feedback and resubmit** - Often, rejection comes with specific concerns.
   Addressing those concerns and resubmitting can be the right path forward.
2. **Discuss in Discord** - Talk with maintainers to better understand the concerns. Sometimes a
   brief conversation reveals a simpler path forward.
3. **Try a different approach** - Submit a new SEP that addresses the same problem differently,
   incorporating what you learned.
4. **Wait for the right moment** - Circumstances change. New use cases emerge, the community
   grows, and priorities shift. An idea rejected today might be welcomed tomorrow.

## Out of Scope

This guide covers contributions to the **core MCP project** - the specification, official SDKs,
and documentation.

Building your own MCP servers, clients, or tools is **not** covered here. For guidance on building
with MCP, see our documentation:

* [Build a Server](/docs/develop/build-server)
* [Build a Client](/docs/develop/build-client)
* [Example Servers](/examples)

If you build something you'd like to share with the community, you can submit it to the
[MCP Registry](/registry/about).

## AI Contributions

We welcome the use of AI tools like Claude or ChatGPT to help with your contributions! If you do
use AI assistance, just let us know in your pull request or issue - a quick note about how you
used it (drafting docs, generating code, brainstorming, etc.) is all we need.

The key is that you understand and can stand behind your contribution:

* **You get it** - You understand what the changes do and can explain them
* **You know why** - You can articulate why the change is needed
* **You've verified it** - You've tested or validated that it works as intended

You can read more about our stance in
[our spec contribution guidelines](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/CONTRIBUTING.md#ai-contributions).

## Code of Conduct

All contributors must follow the
[Code of Conduct](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/CODE_OF_CONDUCT.md).
We expect respectful, professional, and inclusive interactions across all channels.

## License

By contributing, you agree that your contributions will be licensed under:

* **Code and specifications**: Apache License 2.0
* **Documentation** (excluding specifications): CC-BY 4.0

See the
[LICENSE](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/LICENSE) file for
details.